feat(ai): propose_change tool — drafts to pending_changes, never applies

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

lib/ai/agent/tools/propose_change.js

@@ -0,0 +1,41 @@
+import { canAct } from '../../../auth/capability.js';
+import * as pendingChanges from '../../../db/repos/pending_changes.js';
+
+const ENTITY_TYPES = ['task', 'page', 'project', 'ref', 'resource', 'source_doc'];
+const ACTIONS = ['create', 'update', 'delete'];
+
+export const proposeChangeTool = {
+  name: 'propose_change',
+  description: 'Propose a change to the Void. This NEVER applies directly — it creates a draft the owner must approve. Use for creating/updating/deleting tasks, pages, projects, refs, resources.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      entity_type: { type: 'string', enum: ENTITY_TYPES },
+      action: { type: 'string', enum: ACTIONS },
+      entity_id: { type: 'string', description: 'uuid; required for update/delete' },
+      payload: { type: 'object', description: 'fields for the change' },
+      reason: { type: 'string', description: 'one-line rationale shown to the owner' }
+    },
+    required: ['entity_type', 'action', 'payload']
+  },
+  async handler({ entity_type, action, entity_id, payload, reason }, ctx) {
+    const tier = canAct(ctx.agent, action, entity_type);
+    if (tier === 'deny') {
+      return { error: `not permitted to ${action} ${entity_type}` };
+    }
+    // v1: drafting always routes through approval, even for allow-tier agents.
+    const change = await pendingChanges.create({
+      agent_id: ctx.agent.id,
+      entity_type,
+      entity_id: entity_id ?? null,
+      action,
+      payload: payload ?? {},
+      reason: reason ?? null
+    });
+    return {
+      pending_change_id: change.id,
+      applied: false,
+      summary: `${action} ${entity_type}${payload?.title ? ` "${payload.title}"` : ''}`
+    };
+  }
+};