@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-personal-ops-tool.ts

@@ -0,0 +1,197 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
+import { createAgentHarnessTool } from './agent-harness-tool.ts';
+
+type AgentPersonalOpsAction = 'briefing' | 'status' | 'queue' | 'intake' | 'lane' | 'read';
+
+interface AgentPersonalOpsToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly laneId?: unknown;
+  readonly recordId?: unknown;
+  readonly query?: unknown;
+  readonly target?: unknown;
+  readonly fields?: unknown;
+  readonly saveReviewCards?: unknown;
+  readonly saveReview?: unknown;
+  readonly artifactTitle?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+interface AgentPersonalOpsToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+function error(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizePersonalOpsAction(value: unknown): AgentPersonalOpsAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'briefing' || action === 'brief' || action === 'daily' || action === 'daily_brief' || action === 'morning') return 'briefing';
+  if (action === 'status' || action === 'summary' || action === 'overview' || action === 'map' || action === 'list') return 'status';
+  if (action === 'queue' || action === 'queues' || action === 'review_queue' || action === 'review_queues' || action === 'personal_queue' || action === 'ops_queue') return 'queue';
+  if (action === 'intake' || action === 'request' || action === 'route' || action === 'plan' || action === 'triage' || action === 'draft') return 'intake';
+  if (action === 'lane' || action === 'inspect' || action === 'show') return 'lane';
+  if (action === 'read' || action === 'run' || action === 'execute' || action === 'fresh_read' || action === 'refresh') return 'read';
+  return null;
+}
+
+function readAction(args: AgentPersonalOpsToolArgs): AgentPersonalOpsAction {
+  const explicit = normalizePersonalOpsAction(args.action) ?? normalizePersonalOpsAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.recordId)) return 'read';
+  if (readString(args.laneId)) return 'lane';
+  if (readString(args.query) || readString(args.target)) return 'intake';
+  return 'briefing';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function readFields(args: AgentPersonalOpsToolArgs): Record<string, unknown> | undefined {
+  const fields = args.fields && typeof args.fields === 'object' && !Array.isArray(args.fields)
+    ? { ...(args.fields as Record<string, unknown>) }
+    : {};
+  if (args.saveReviewCards !== undefined) fields.saveReviewCards = args.saveReviewCards;
+  if (args.saveReview !== undefined) fields.saveReview = args.saveReview;
+  const artifactTitle = readString(args.artifactTitle);
+  if (artifactTitle) fields.artifactTitle = artifactTitle;
+  return Object.keys(fields).length > 0 ? fields : undefined;
+}
+
+function briefingArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'personal_ops_briefing',
+    query: args.query,
+    target: args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function statusArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'personal_ops',
+    includeParameters: args.includeParameters,
+  });
+}
+
+function intakeArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'personal_ops_intake',
+    query: args.query,
+    target: args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function queueArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'personal_ops_queue',
+    query: args.query,
+    target: args.target,
+    limit: args.limit,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function laneArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'personal_ops_lane',
+    laneId: args.laneId,
+    target: args.target,
+    query: args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function readArgs(args: AgentPersonalOpsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'run_personal_ops_read',
+    laneId: args.laneId,
+    recordId: args.recordId,
+    target: args.target,
+    query: args.query,
+    fields: readFields(args),
+    includeParameters: args.includeParameters,
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  });
+}
+
+export function createAgentPersonalOpsTool(deps: AgentPersonalOpsToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'personal_ops',
+      description: 'Plan and run safe Personal Ops workflows.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['briefing', 'status', 'queue', 'intake', 'lane', 'read'],
+            description: 'Discovery actions are read-only; read needs confirmation.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          laneId: { type: 'string', enum: ['inbox', 'calendar', 'notes', 'tasks', 'reminders', 'routines', 'delivery'], description: 'Personal Ops lane id.' },
+          recordId: { type: 'string', description: 'Selected inbox/calendar read operation record id.' },
+          query: { type: 'string', description: 'Personal operations request or lane lookup text.' },
+          target: { type: 'string', description: 'Alias for query or lookup target.' },
+          fields: { type: 'object', additionalProperties: true, description: 'Connector input fields for action:read.' },
+          saveReviewCards: { type: 'boolean', description: 'For action:read, save redacted review cards as a local artifact.' },
+          saveReview: { type: 'boolean', description: 'Alias for saveReviewCards.' },
+          artifactTitle: { type: 'string', description: 'Optional title for a saved read-review artifact.' },
+          includeParameters: { type: 'boolean', description: 'Include bounded operation schema and route detail where supported.' },
+          limit: { type: 'number', description: 'Maximum briefing or intake rows.' },
+          confirm: { type: 'boolean', description: 'Required true for action:read.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing action:read.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentPersonalOpsToolArgs;
+      const action = readAction(args);
+
+      if (action === 'briefing') return harnessTool.execute(briefingArgs(args));
+      if (action === 'status') return harnessTool.execute(statusArgs(args));
+      if (action === 'queue') return harnessTool.execute(queueArgs(args));
+      if (action === 'intake') return harnessTool.execute(intakeArgs(args));
+      if (action === 'lane') return harnessTool.execute(laneArgs(args));
+      if (action === 'read') return harnessTool.execute(readArgs(args));
+
+      return error('Unknown Personal Ops action. Use action:"briefing" for the user-first daily plan.');
+    },
+  };
+}
+
+export function registerAgentPersonalOpsTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('personal_ops')) registry.register(createAgentPersonalOpsTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

package/src/tools/agent-policy-explanation.ts

@@ -0,0 +1,415 @@
+import type { PermissionCategory, PermissionDecisionReasonCode, PermissionDecisionSource } from '@pellux/goodvibes-sdk/platform/permissions';
+import { analyzePermissionRequest } from '@pellux/goodvibes-sdk/platform/permissions';
+import type { ToolDefinition } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext } from '../input/command-registry.ts';
+import { fallbackPermissionCategoryForArgs } from '../runtime/tool-permission-safety.ts';
+import { HARNESS_MODE_DESCRIPTORS } from './agent-harness-mode-catalog.ts';
+import { explainAgentToolPolicyInvocation } from './agent-tool-policy-guard.ts';
+
+type PolicyExplanationStatus = 'allowed' | 'confirmation_required' | 'denied';
+type PermissionPredictionOutcome = 'allowed' | 'prompt' | 'denied';
+type PermissionToolKey =
+  | 'read'
+  | 'write'
+  | 'edit'
+  | 'exec'
+  | 'find'
+  | 'fetch'
+  | 'analyze'
+  | 'inspect'
+  | 'agent'
+  | 'state'
+  | 'workflow'
+  | 'registry'
+  | 'delegate'
+  | 'mcp';
+
+export interface AgentPolicyExplainArgs {
+  readonly toolName?: unknown;
+  readonly tool?: unknown;
+  readonly toolArgs?: unknown;
+  readonly args?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+}
+
+export type AgentPolicyExplanationResolution =
+  | { readonly status: 'found'; readonly explanation: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+interface PermissionPrediction {
+  readonly outcome: PermissionPredictionOutcome;
+  readonly sourceLayer: PermissionDecisionSource | 'user_prompt_pending';
+  readonly reasonCode: PermissionDecisionReasonCode | 'prompt_required';
+  readonly mode: string;
+  readonly reason: string;
+  readonly configuredAction?: string;
+}
+
+const TOOL_CONFIG_KEYS: Readonly<Record<string, PermissionToolKey>> = {
+  read: 'read',
+  write: 'write',
+  edit: 'edit',
+  exec: 'exec',
+  find: 'find',
+  fetch: 'fetch',
+  analyze: 'analyze',
+  inspect: 'inspect',
+  agent: 'agent',
+  state: 'state',
+  workflow: 'workflow',
+  registry: 'registry',
+  goodvibes_context: 'state',
+  goodvibes_settings: 'write',
+  delegate: 'delegate',
+  mcp: 'mcp',
+};
+
+const SECRET_KEY_RE = /(?:api[_-]?key|token|secret|password|authorization|auth|bearer|webhook)/i;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readBoolean(value: unknown): boolean {
+  return value === true || (typeof value === 'string' && ['true', 'yes', 'apply', 'run'].includes(value.trim().toLowerCase()));
+}
+
+function readToolArgs(args: AgentPolicyExplainArgs): Record<string, unknown> {
+  if (isRecord(args.toolArgs)) return args.toolArgs;
+  if (isRecord(args.args)) return args.args;
+  return {};
+}
+
+function redactValue(key: string, value: unknown, depth = 0): unknown {
+  if (SECRET_KEY_RE.test(key)) return '<redacted>';
+  if (depth > 2) return '<nested>';
+  if (Array.isArray(value)) return value.slice(0, 8).map((entry) => redactValue(key, entry, depth + 1));
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).slice(0, 20).map(([entryKey, entryValue]) => [entryKey, redactValue(entryKey, entryValue, depth + 1)]));
+  }
+  if (typeof value === 'string' && /(?:[?&](?:token|secret|password|api[_-]?key)=|bearer\s+)/i.test(value)) return '<redacted>';
+  if (typeof value === 'string' && value.length > 240) return `${value.slice(0, 237)}...`;
+  return value;
+}
+
+function redactArgs(args: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(args).slice(0, 30).map(([key, value]) => [key, redactValue(key, value)]));
+}
+
+function hasSchemaProperty(definition: ToolDefinition | undefined, property: string): boolean {
+  const parameters = definition?.parameters;
+  if (!isRecord(parameters)) return false;
+  const properties = parameters.properties;
+  return isRecord(properties) && property in properties;
+}
+
+function sideEffects(definition: ToolDefinition | undefined): readonly string[] {
+  return Array.isArray(definition?.sideEffects) ? definition.sideEffects.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+function findToolDefinition(toolRegistry: ToolRegistry, name: string): ToolDefinition | undefined {
+  return toolRegistry.getToolDefinitions().find((definition) => definition.name === name);
+}
+
+function toolSearchText(definition: ToolDefinition): string {
+  return [definition.name, definition.description, ...(definition.sideEffects ?? [])].filter(Boolean).join('\n').toLowerCase();
+}
+
+function resolveToolName(toolRegistry: ToolRegistry, args: AgentPolicyExplainArgs): {
+  readonly status: 'found' | 'ambiguous' | 'missing_lookup';
+  readonly toolName?: string;
+  readonly input?: string;
+  readonly candidates?: readonly Record<string, unknown>[];
+  readonly explicit?: boolean;
+} {
+  const explicit = readString(args.toolName) || readString(args.tool);
+  if (explicit) return { status: 'found', toolName: explicit, input: explicit, explicit: true };
+  const input = readString(args.target) || readString(args.query);
+  if (!input) return { status: 'missing_lookup' };
+
+  const definitions = toolRegistry.getToolDefinitions();
+  const exact = definitions.find((definition) => definition.name === input);
+  if (exact) return { status: 'found', toolName: exact.name, input, explicit: false };
+  const lowered = input.toLowerCase();
+  const insensitive = definitions.find((definition) => definition.name.toLowerCase() === lowered);
+  if (insensitive) return { status: 'found', toolName: insensitive.name, input, explicit: false };
+  const matches = definitions.filter((definition) => toolSearchText(definition).includes(lowered)).slice(0, 8);
+  if (matches.length === 1) return { status: 'found', toolName: matches[0]!.name, input, explicit: false };
+  if (matches.length > 1) {
+    return {
+      status: 'ambiguous',
+      input,
+      candidates: matches.map((definition) => ({
+        toolName: definition.name,
+        description: definition.description,
+        modelRoute: `security action:"explain" toolName:"${definition.name}" toolArgs:{...}`,
+      })),
+    };
+  }
+  return { status: 'found', toolName: input, input, explicit: false };
+}
+
+function readConfigValue(context: CommandContext, key: string): unknown {
+  try {
+    const manager = context.platform.configManager as unknown as { get?: (key: string) => unknown };
+    return manager.get?.(key);
+  } catch {
+    return undefined;
+  }
+}
+
+function readPermissionMode(context: CommandContext): string {
+  const configured = readString(readConfigValue(context, 'permissions.mode'));
+  if (configured) return configured;
+  const mode = context.platform.config?.permissions?.mode;
+  return typeof mode === 'string' && mode ? mode : 'prompt';
+}
+
+function readPermissionToolAction(context: CommandContext, key: PermissionToolKey): string | null {
+  const configured = readString(readConfigValue(context, `permissions.tools.${key}`));
+  if (configured) return configured;
+  const action = context.platform.config?.permissions?.tools?.[key];
+  return typeof action === 'string' && action ? action : null;
+}
+
+function readAutoApprove(context: CommandContext): boolean {
+  const configured = readConfigValue(context, 'behavior.autoApprove');
+  if (typeof configured === 'boolean') return configured;
+  return context.platform.config?.behavior?.autoApprove === true;
+}
+
+function predictPermission(context: CommandContext, toolName: string, category: PermissionCategory): PermissionPrediction {
+  if (readAutoApprove(context)) {
+    return {
+      outcome: 'allowed',
+      sourceLayer: 'config_policy',
+      reasonCode: 'config_allow',
+      mode: readPermissionMode(context),
+      reason: 'Automatic tool approval is enabled for this session.',
+    };
+  }
+
+  const mode = readPermissionMode(context);
+  if (mode === 'allow-all') {
+    return {
+      outcome: 'allowed',
+      sourceLayer: 'runtime_mode',
+      reasonCode: 'mode_allow_all',
+      mode,
+      reason: 'Permission mode is allow-all, so the permission layer will not prompt.',
+    };
+  }
+
+  if (mode === 'custom') {
+    const toolConfigKey = TOOL_CONFIG_KEYS[toolName];
+    if (!toolConfigKey) {
+      return {
+        outcome: 'prompt',
+        sourceLayer: 'user_prompt_pending',
+        reasonCode: 'prompt_required',
+        mode,
+        reason: 'Custom permission mode has no per-tool rule for this tool.',
+      };
+    }
+    const configuredAction = readPermissionToolAction(context, toolConfigKey) ?? 'prompt';
+    if (configuredAction === 'allow') {
+      return {
+        outcome: 'allowed',
+        sourceLayer: 'config_policy',
+        reasonCode: 'config_allow',
+        mode,
+        configuredAction,
+        reason: `Custom permission rule permissions.tools.${toolConfigKey} is allow.`,
+      };
+    }
+    if (configuredAction === 'deny') {
+      return {
+        outcome: 'denied',
+        sourceLayer: 'config_policy',
+        reasonCode: 'config_deny',
+        mode,
+        configuredAction,
+        reason: `Custom permission rule permissions.tools.${toolConfigKey} is deny.`,
+      };
+    }
+    return {
+      outcome: 'prompt',
+      sourceLayer: 'user_prompt_pending',
+      reasonCode: 'prompt_required',
+      mode,
+      configuredAction,
+      reason: `Custom permission rule permissions.tools.${toolConfigKey} is prompt.`,
+    };
+  }
+
+  if (category === 'read') {
+    return {
+      outcome: 'allowed',
+      sourceLayer: 'config_policy',
+      reasonCode: 'config_allow',
+      mode,
+      reason: 'Prompt mode auto-allows read-only actions.',
+    };
+  }
+
+  return {
+    outcome: 'prompt',
+    sourceLayer: 'user_prompt_pending',
+    reasonCode: 'prompt_required',
+    mode,
+    reason: `Prompt mode asks before ${category} actions.`,
+  };
+}
+
+function harnessModeRequiresConfirmation(toolName: string, toolArgs: Record<string, unknown>): boolean {
+  if (toolName !== 'agent_harness') return false;
+  const mode = readString(toolArgs.mode);
+  if (!mode) return false;
+  return HARNESS_MODE_DESCRIPTORS.some((descriptor) => descriptor.id === mode && descriptor.requiresConfirmation === true);
+}
+
+function confirmationState(toolName: string, toolArgs: Record<string, unknown>, definition: ToolDefinition | undefined, category: PermissionCategory): {
+  readonly required: boolean;
+  readonly confirmed: boolean;
+  readonly reason: string;
+} {
+  const schemaRequestsConfirmation = hasSchemaProperty(definition, 'confirm') && hasSchemaProperty(definition, 'explicitUserRequest');
+  const required = harnessModeRequiresConfirmation(toolName, toolArgs)
+    || (schemaRequestsConfirmation && category !== 'read');
+  if (!required) {
+    return {
+      required: false,
+      confirmed: true,
+      reason: 'The tool contract does not require typed confirmation for this read-only route.',
+    };
+  }
+  const confirmed = readBoolean(toolArgs.confirm) && readString(toolArgs.explicitUserRequest).length > 0;
+  return {
+    required,
+    confirmed,
+    reason: confirmed
+      ? 'Typed confirmation is present: confirm:true and explicitUserRequest are set.'
+      : 'Typed confirmation is required: pass confirm:true and explicitUserRequest.',
+  };
+}
+
+function statusFor(
+  guard: ReturnType<typeof explainAgentToolPolicyInvocation>,
+  permission: PermissionPrediction,
+  confirmation: ReturnType<typeof confirmationState>,
+): PolicyExplanationStatus {
+  if (guard.status === 'denied' || permission.outcome === 'denied') return 'denied';
+  if (permission.outcome === 'prompt' || (confirmation.required && !confirmation.confirmed)) return 'confirmation_required';
+  return 'allowed';
+}
+
+function userExplanation(status: PolicyExplanationStatus, category: PermissionCategory): string {
+  if (status === 'denied') return 'This action is denied before execution. Use the recommended safer route or change policy explicitly.';
+  if (status === 'confirmation_required') return `This ${category} action is available only after the user-visible confirmation or permission prompt is satisfied.`;
+  return `This ${category} action is allowed by the current Agent and permission policy.`;
+}
+
+export function explainAgentPolicyDecision(
+  context: CommandContext,
+  toolRegistry: ToolRegistry,
+  args: AgentPolicyExplainArgs,
+): AgentPolicyExplanationResolution {
+  const resolved = resolveToolName(toolRegistry, args);
+  if (resolved.status === 'missing_lookup') {
+    return {
+      status: 'missing_lookup',
+      usage: 'policy_explain requires toolName or a target/query matching one model tool.',
+    };
+  }
+  if (resolved.status === 'ambiguous') {
+    return {
+      status: 'ambiguous',
+      input: resolved.input ?? '',
+      candidates: resolved.candidates ?? [],
+    };
+  }
+
+  const toolName = resolved.toolName!;
+  const toolArgs = readToolArgs(args);
+  const definition = findToolDefinition(toolRegistry, toolName);
+  const category = fallbackPermissionCategoryForArgs(toolName, toolArgs);
+  const analysis = analyzePermissionRequest(toolName, toolArgs, category);
+  const guard = explainAgentToolPolicyInvocation(toolName, toolArgs);
+  const permission = predictPermission(context, toolName, category);
+  const confirmation = confirmationState(toolName, toolArgs, definition, category);
+  const status = statusFor(guard, permission, confirmation);
+  const requiredActions = [
+    ...(permission.outcome === 'prompt' ? [`Answer the ${category} permission prompt for ${toolName}.`] : []),
+    ...(confirmation.required && !confirmation.confirmed ? ['Call the route with confirm:true and explicitUserRequest.'] : []),
+  ];
+
+  return {
+    status: 'found',
+    explanation: {
+      status,
+      toolName,
+      registered: definition !== undefined,
+      category,
+      userExplanation: userExplanation(status, category),
+      policyLayers: [
+        {
+          layer: 'Agent route guard',
+          outcome: guard.status,
+          reason: guard.reason,
+          ...(guard.allowedModes ? { allowedModes: guard.allowedModes } : {}),
+        },
+        {
+          layer: 'Permission mode',
+          outcome: permission.outcome,
+          mode: permission.mode,
+          sourceLayer: permission.sourceLayer,
+          reasonCode: permission.reasonCode,
+          reason: permission.reason,
+          ...(permission.configuredAction ? { configuredAction: permission.configuredAction } : {}),
+        },
+        {
+          layer: 'Tool confirmation',
+          outcome: confirmation.required ? (confirmation.confirmed ? 'confirmed' : 'required') : 'not_required',
+          reason: confirmation.reason,
+        },
+      ],
+      requiredActions,
+      analysis,
+      preflight: {
+        approvedWithoutMoreInput: status === 'allowed',
+        permissionOutcome: permission.outcome,
+        toolConfirmationRequired: confirmation.required,
+        toolConfirmationSatisfied: confirmation.confirmed,
+      },
+      toolArgs: redactArgs(toolArgs),
+      routes: {
+        explain: `security action:"explain" toolName:"${toolName}" toolArgs:{...}`,
+        inspectTool: `agent_harness mode:"tool" toolName:"${toolName}" includeParameters:true`,
+        permissions: 'workspace action:"actions" categoryId:"tools-permissions"',
+        securityPosture: 'security action:"status" includeParameters:true',
+      },
+      notes: [
+        'This is a read-only preflight; final execution still uses the live safety guard.',
+        'Secret-looking argument values are redacted in this explanation.',
+      ],
+      ...(args.includeParameters === true && definition ? {
+        toolDefinition: {
+          name: definition.name,
+          description: definition.description,
+          sideEffects: sideEffects(definition),
+          hasConfirmParameter: hasSchemaProperty(definition, 'confirm'),
+          hasExplicitUserRequestParameter: hasSchemaProperty(definition, 'explicitUserRequest'),
+        },
+      } : {}),
+      ...(resolved.input ? { lookup: { input: resolved.input, explicit: resolved.explicit === true } } : {}),
+    },
+  };
+}