aiden-runtime 4.1.4 → 4.5.0

package/dist/tools/v4/index.js

@@ -26,6 +26,7 @@ exports.sessionSummaryTool = exports.memoryRemoveTool = void 0;
 exports.registerReadOnlyTools = registerReadOnlyTools;
 exports.registerWriteTools = registerWriteTools;
 exports.registerAllTools = registerAllTools;
+const dryRun_1 = require("../../core/v4/dryRun");
 const webSearch_1 = require("./web/webSearch");
 const webFetch_1 = require("./web/webFetch");
 const webPage_1 = require("./web/webPage");
@@ -96,54 +97,61 @@ const subagentFanout_1 = require("./subagent/subagentFanout");
  * the full set).
  */
 function registerReadOnlyTools(registry) {
-    registry.register(webSearch_1.webSearchTool);
-    registry.register(webFetch_1.webFetchTool);
-    registry.register(webPage_1.webPageTool);
-    registry.register(deepResearch_1.deepResearchTool);
+    // v4.4 Phase 4 — every handler is funneled through withDryRun so
+    // AIDEN_DRYRUN=1 short-circuits `execute` to a preview. Read-only
+    // tools pass through unchanged (the HOC returns the handler as-is
+    // when `mutates: false`); the wrapper is cheap (`if (!mutates)
+    // return handler`) and keeps the registration call sites uniform
+    // across read/write tool sets.
+    const register = (h) => registry.register((0, dryRun_1.withDryRun)(h));
+    register(webSearch_1.webSearchTool);
+    register(webFetch_1.webFetchTool);
+    register(webPage_1.webPageTool);
+    register(deepResearch_1.deepResearchTool);
     // Phase 16f: open_url uses shell launch (start chrome / open / xdg-open)
     // for "open X in browser" requests — bypasses Playwright detection.
-    registry.register(openUrl_1.openUrlTool);
+    register(openUrl_1.openUrlTool);
     // Phase 23.4a: youtube_search returns real /watch?v= URLs scraped
     // from youtube.com/results. media-search uses it before open_url so
     // the URL provenance gate has a candidate set to validate against —
     // closes the URL-hallucination failure mode where the model invented
     // 11-char IDs.
-    registry.register(youtubeSearch_1.youtubeSearchTool);
-    registry.register(fileRead_1.fileReadTool);
-    registry.register(fileList_1.fileListTool);
-    registry.register(browserScreenshot_1.browserScreenshotTool);
-    registry.register(browserExtract_1.browserExtractTool);
-    registry.register(browserGetUrl_1.browserGetUrlTool);
-    registry.register(sessionSearch_1.sessionSearchTool);
-    registry.register(sessionList_1.sessionListTool);
+    register(youtubeSearch_1.youtubeSearchTool);
+    register(fileRead_1.fileReadTool);
+    register(fileList_1.fileListTool);
+    register(browserScreenshot_1.browserScreenshotTool);
+    register(browserExtract_1.browserExtractTool);
+    register(browserGetUrl_1.browserGetUrlTool);
+    register(sessionSearch_1.sessionSearchTool);
+    register(sessionList_1.sessionListTool);
     // Phase v4.1.2-memory-C: recall_session reads SessionDistillation
     // files written by Phase A+B. Sits alongside session_search — the
     // two have distinct purposes (FTS5-over-messages vs ranked
     // distillation summaries); descriptions force the right model
     // choice.
-    registry.register(recallSession_1.recallSessionTool);
-    registry.register(skillsList_1.skillsListTool);
-    registry.register(skillView_1.skillViewTool);
-    registry.register(systemInfo_1.systemInfoTool);
-    registry.register(nowPlaying_1.nowPlayingTool);
-    registry.register(naturalEvents_1.naturalEventsTool);
+    register(recallSession_1.recallSessionTool);
+    register(skillsList_1.skillsListTool);
+    register(skillView_1.skillViewTool);
+    register(systemInfo_1.systemInfoTool);
+    register(nowPlaying_1.nowPlayingTool);
+    register(naturalEvents_1.naturalEventsTool);
     // Phase v4.1.2-followup-3 — computer-control read-only tools.
-    registry.register(screenshot_1.screenshotTool);
-    registry.register(osProcessList_1.osProcessListTool);
-    registry.register(clipboardRead_1.clipboardReadTool);
+    register(screenshot_1.screenshotTool);
+    register(osProcessList_1.osProcessListTool);
+    register(clipboardRead_1.clipboardReadTool);
     // v4.1.4-media — GSMTC session enumeration (read). Pair with
     // mediaTransport (write) in the write-tools registration below.
-    registry.register(mediaSessions_1.mediaSessionsTool);
-    registry.register((0, lookupToolSchema_1.makeLookupToolSchema)(registry));
+    register(mediaSessions_1.mediaSessionsTool);
+    register((0, lookupToolSchema_1.makeLookupToolSchema)(registry));
     // Phase v4.1-subagent — register a stub for subagent_fanout so its
     // schema is visible to the agent loop, the MCP server, and the
     // /tools slash command BEFORE the runtime resolves provider /
     // adapter / agent dependencies. The full runtime calls
-    // `registry.register(makeSubagentFanoutTool({...real opts}))` to
+    // `register(makeSubagentFanoutTool({...real opts}))` to
     // replace this stub once `buildAgentRuntime` has those handles.
     // Until then, calling the stub returns a clear "not wired" error
     // rather than crashing.
-    registry.register(makeSubagentFanoutStub());
+    register(makeSubagentFanoutStub());
 }
 /** Stub used until the runtime wires real provider / adapter / agent
  *  dependencies. Returns the SAME schema as the real tool so MCP and
@@ -156,7 +164,7 @@ function makeSubagentFanoutStub() {
             apiMode: 'chat_completions',
             async call() {
                 throw new Error('subagent_fanout: tool not wired — runtime did not replace the stub. ' +
-                    'Call registry.register(makeSubagentFanoutTool({...})) after buildAgentRuntime.');
+                    'Call register(makeSubagentFanoutTool({...})) after buildAgentRuntime.');
             },
         },
         runChild: async () => {
@@ -170,50 +178,55 @@ function makeSubagentFanoutStub() {
  * engine — the registration order doesn't matter for that.
  */
 function registerWriteTools(registry) {
-    registry.register(fileWrite_1.fileWriteTool);
-    registry.register(filePatch_1.filePatchTool);
-    registry.register(fileDelete_1.fileDeleteTool);
-    registry.register(fileMove_1.fileMoveTool);
-    registry.register(fileCopy_1.fileCopyTool);
-    registry.register(shellExec_1.shellExecTool);
-    registry.register(browserNavigate_1.browserNavigateTool);
-    registry.register(browserClick_1.browserClickTool);
-    registry.register(browserType_1.browserTypeTool);
-    registry.register(browserFill_1.browserFillTool);
-    registry.register(browserScroll_1.browserScrollTool);
-    registry.register(browserClose_1.browserCloseTool);
-    registry.register(executeCode_1.executeCodeTool);
-    registry.register(processSpawn_1.processSpawnTool);
-    registry.register(processList_1.processListTool);
-    registry.register(processLogRead_1.processLogReadTool);
-    registry.register(processKill_1.processKillTool);
-    registry.register(processWait_1.processWaitTool);
+    // v4.4 Phase 4 — same withDryRun wrap as registerReadOnlyTools.
+    // Write tools are where the preview path is actually hot — when
+    // AIDEN_DRYRUN=1, each handler's `buildPreview` is called instead
+    // of `execute`.
+    const register = (h) => registry.register((0, dryRun_1.withDryRun)(h));
+    register(fileWrite_1.fileWriteTool);
+    register(filePatch_1.filePatchTool);
+    register(fileDelete_1.fileDeleteTool);
+    register(fileMove_1.fileMoveTool);
+    register(fileCopy_1.fileCopyTool);
+    register(shellExec_1.shellExecTool);
+    register(browserNavigate_1.browserNavigateTool);
+    register(browserClick_1.browserClickTool);
+    register(browserType_1.browserTypeTool);
+    register(browserFill_1.browserFillTool);
+    register(browserScroll_1.browserScrollTool);
+    register(browserClose_1.browserCloseTool);
+    register(executeCode_1.executeCodeTool);
+    register(processSpawn_1.processSpawnTool);
+    register(processList_1.processListTool);
+    register(processLogRead_1.processLogReadTool);
+    register(processKill_1.processKillTool);
+    register(processWait_1.processWaitTool);
     // Phase 9: memory write tools (gated by MemoryGuard for read-back
     // verification, then by the approval engine like every other write).
-    registry.register(memoryAdd_1.memoryAddTool);
-    registry.register(memoryReplace_1.memoryReplaceTool);
-    registry.register(memoryRemove_1.memoryRemoveTool);
+    register(memoryAdd_1.memoryAddTool);
+    register(memoryReplace_1.memoryReplaceTool);
+    register(memoryRemove_1.memoryRemoveTool);
     // Phase v4.1.2 alive-core: cross-session continuity via /quit auto-summary.
-    registry.register(sessionSummary_1.sessionSummaryTool);
+    register(sessionSummary_1.sessionSummaryTool);
     // Phase 10: skill_manage — mutating, also goes through the approval
     // engine. skills_list / skill_view stay in registerReadOnlyTools.
-    registry.register(skillManage_1.skillManageTool);
+    register(skillManage_1.skillManageTool);
     // Phase v4.1.2-update: natural-language entry to the same install
     // executor that /update install uses. Two-step confirmation gate
     // (confirm:false → status; confirm:true → install).
-    registry.register(aidenSelfUpdate_1.aidenSelfUpdateTool);
+    register(aidenSelfUpdate_1.aidenSelfUpdateTool);
     // Phase v4.1.2-followup-3 — computer-control mutating tools. All
     // route through the approval engine like every other write.
-    registry.register(mediaKey_1.mediaKeyTool);
-    registry.register(volumeSet_1.volumeSetTool);
-    registry.register(appLaunch_1.appLaunchTool);
-    registry.register(appClose_1.appCloseTool);
-    registry.register(clipboardWrite_1.clipboardWriteTool);
+    register(mediaKey_1.mediaKeyTool);
+    register(volumeSet_1.volumeSetTool);
+    register(appLaunch_1.appLaunchTool);
+    register(appClose_1.appCloseTool);
+    register(clipboardWrite_1.clipboardWriteTool);
     // v4.1.4-media — verified GSMTC transport (replaces mediaKey for
     // the "name an app, play/pause it" case) + focused-window SendKeys
     // (escape hatch when GSMTC doesn't enumerate the surface).
-    registry.register(mediaTransport_1.mediaTransportTool);
-    registry.register(appInput_1.appInputTool);
+    register(mediaTransport_1.mediaTransportTool);
+    register(appInput_1.appInputTool);
 }
 /** Register every v4 tool. Most callers want this. */
 function registerAllTools(registry) {

package/dist/tools/v4/memory/memoryAdd.js

@@ -17,6 +17,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryAddTool = void 0;
+const dryRun_1 = require("../../../core/v4/dryRun");
 exports.memoryAddTool = {
     schema: {
         name: 'memory_add',
@@ -37,6 +38,19 @@ exports.memoryAddTool = {
     category: 'write',
     mutates: true,
     toolset: 'memory',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const file = args.file === 'user' ? 'user' : 'memory';
+        const content = String(args.content ?? '');
+        return {
+            tool: 'memory_add',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'memory_write', op: 'add', bullet: (0, dryRun_1.truncatePreview)(content) }],
+            detectedRisks: [],
+            summary: `Would append to ${file === 'user' ? 'USER.md' : 'MEMORY.md'}: "${(0, dryRun_1.truncatePreview)(content, 80)}"`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.memoryGuard) {
             return { success: false, error: 'memory guard not configured' };

package/dist/tools/v4/memory/memoryRemove.js

@@ -31,6 +31,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryRemoveTool = void 0;
 const memoryGuard_1 = require("../../../moat/memoryGuard");
+const dryRun_1 = require("../../../core/v4/dryRun");
 /** Section in MEMORY.md that Phase D promotion writes to. */
 const DURABLE_FACTS_HEADER = '## Durable facts';
 exports.memoryRemoveTool = {
@@ -59,6 +60,19 @@ exports.memoryRemoveTool = {
     category: 'write',
     mutates: true,
     toolset: 'memory',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const file = args.file === 'user' ? 'user' : 'memory';
+        const text = String(args.text ?? '');
+        return {
+            tool: 'memory_remove',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'memory_write', op: 'remove', pattern: (0, dryRun_1.truncatePreview)(text, 80) }],
+            detectedRisks: [],
+            summary: `Would remove from ${file === 'user' ? 'USER.md' : 'MEMORY.md'}: "${(0, dryRun_1.truncatePreview)(text, 80)}"`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.memoryGuard) {
             return { success: false, error: 'memory guard not configured' };

package/dist/tools/v4/memory/memoryReplace.js

@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryReplaceTool = void 0;
+const dryRun_1 = require("../../../core/v4/dryRun");
 exports.memoryReplaceTool = {
     schema: {
         name: 'memory_replace',
@@ -37,6 +38,20 @@ exports.memoryReplaceTool = {
     category: 'write',
     mutates: true,
     toolset: 'memory',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const file = args.file === 'user' ? 'user' : 'memory';
+        const oldText = String(args.old_text ?? args.oldText ?? '');
+        const newText = String(args.new_text ?? args.newText ?? '');
+        return {
+            tool: 'memory_replace',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'memory_write', op: 'replace', pattern: (0, dryRun_1.truncatePreview)(oldText, 80), bullet: (0, dryRun_1.truncatePreview)(newText, 80) }],
+            detectedRisks: [],
+            summary: `Would replace in ${file === 'user' ? 'USER.md' : 'MEMORY.md'}: "${(0, dryRun_1.truncatePreview)(oldText, 40)}" → "${(0, dryRun_1.truncatePreview)(newText, 40)}"`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.memoryGuard) {
             return { success: false, error: 'memory guard not configured' };

package/dist/tools/v4/memory/sessionSummary.js

@@ -100,6 +100,18 @@ exports.sessionSummaryTool = {
     category: 'write',
     mutates: true,
     toolset: 'memory',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args, ctx) {
+        const sessionId = String(args.session_id ?? args.sessionId ?? ctx.sessionId ?? 'current');
+        return {
+            tool: 'session_summary',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'session_distill', session_id: sessionId }],
+            detectedRisks: [],
+            summary: `Would distill session ${sessionId} into Recent-sessions section of MEMORY.md`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.memoryGuard) {
             return { success: false, error: 'memory guard not configured' };

package/dist/tools/v4/process/processKill.js

@@ -31,6 +31,25 @@ exports.processKillTool = {
     category: 'write',
     mutates: true,
     toolset: 'process',
+    riskTier: 'dangerous', // v4.4 Phase 1
+    buildPreview(args, ctx) {
+        const id = String(args.id ?? '').trim();
+        const signal = args.signal || 'SIGTERM';
+        let pid = -1;
+        if (ctx.processes && id) {
+            const h = ctx.processes.get(id);
+            if (h && typeof h.pid === 'number')
+                pid = h.pid;
+        }
+        return {
+            tool: 'process_kill',
+            args,
+            riskTier: 'dangerous',
+            sideEffects: [{ type: 'process_kill', pid, signal }],
+            detectedRisks: signal === 'SIGKILL' ? ['SIGKILL'] : [],
+            summary: `Would send ${signal} to process ${id}${pid > 0 ? ` (pid ${pid})` : ''}`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.processes) {
             return { success: false, error: 'process registry not configured' };

package/dist/tools/v4/process/processList.js

@@ -21,6 +21,7 @@ exports.processListTool = {
     category: 'read',
     mutates: false,
     toolset: 'process',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(_args, ctx) {
         if (!ctx.processes) {
             return { success: false, error: 'process registry not configured' };

package/dist/tools/v4/process/processLogRead.js

@@ -31,6 +31,7 @@ exports.processLogReadTool = {
     category: 'read',
     mutates: false,
     toolset: 'process',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         if (!ctx.processes) {
             return { success: false, error: 'process registry not configured' };

package/dist/tools/v4/process/processSpawn.js

@@ -32,6 +32,19 @@ exports.processSpawnTool = {
     category: 'execute',
     mutates: true,
     toolset: 'process',
+    riskTier: 'dangerous', // v4.4 Phase 1
+    buildPreview(args, ctx) {
+        const command = String(args.command ?? '').trim();
+        const cwd = typeof args.cwd === 'string' ? args.cwd : ctx.cwd;
+        return {
+            tool: 'process_spawn',
+            args,
+            riskTier: 'dangerous',
+            sideEffects: [{ type: 'process_spawn', command, args: [] }],
+            detectedRisks: [],
+            summary: `Would spawn background process: \`${command.length > 80 ? command.slice(0, 80) + '…' : command}\` in ${cwd}`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.processes) {
             return { success: false, error: 'process registry not configured' };

package/dist/tools/v4/process/processWait.js

@@ -33,6 +33,7 @@ exports.processWaitTool = {
     category: 'read',
     mutates: false,
     toolset: 'process',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         if (!ctx.processes) {
             return { success: false, error: 'process registry not configured' };

package/dist/tools/v4/sessions/recallSession.js

@@ -78,6 +78,7 @@ exports.recallSessionTool = {
     category: 'read',
     mutates: false,
     toolset: 'sessions',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         if (!ctx.paths?.root) {
             return {

package/dist/tools/v4/sessions/sessionList.js

@@ -40,6 +40,7 @@ exports.sessionListTool = {
     category: 'read',
     mutates: false,
     toolset: 'sessions',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         if (!ctx.sessions) {
             return {

package/dist/tools/v4/sessions/sessionSearch.js

@@ -45,6 +45,7 @@ exports.sessionSearchTool = {
     category: 'read',
     mutates: false,
     toolset: 'sessions',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         const query = String(args.query ?? '').trim();
         if (!query)

package/dist/tools/v4/skills/lookupToolSchema.js

@@ -45,6 +45,7 @@ function makeLookupToolSchema(registry) {
         category: 'read',
         mutates: false,
         toolset: 'skills',
+        riskTier: 'safe', // v4.4 Phase 1
         async execute(args) {
             const name = String(args.toolName ?? args.name ?? '').trim();
             if (!name)
@@ -63,6 +64,7 @@ function makeLookupToolSchema(registry) {
                 category: handler.category,
                 mutates: handler.mutates,
                 toolset: handler.toolset,
+                riskTier: 'safe', // v4.4 Phase 1
             };
         },
     };

package/dist/tools/v4/skills/skillManage.js

@@ -78,6 +78,19 @@ exports.skillManageTool = {
     category: 'write',
     mutates: true,
     toolset: 'skills',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const action = typeof args.action === 'string' ? args.action : '';
+        const name = typeof args.name === 'string' ? args.name : '';
+        return {
+            tool: 'skill_manage',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'skill_write', op: action, name }],
+            detectedRisks: action === 'delete' ? ['skill_delete'] : [],
+            summary: `Would ${action} skill: ${name}`,
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.skillLoader || !ctx.paths) {
             return { success: false, error: 'No skill loader configured' };

package/dist/tools/v4/skills/skillView.js

@@ -38,6 +38,7 @@ exports.skillViewTool = {
     category: 'read',
     mutates: false,
     toolset: 'skills',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(args, ctx) {
         if (!ctx.skillLoader) {
             return { success: false, error: 'No skill loader configured' };

package/dist/tools/v4/skills/skillsList.js

@@ -31,6 +31,7 @@ exports.skillsListTool = {
     category: 'read',
     mutates: false,
     toolset: 'skills',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(_args, ctx) {
         if (!ctx.skillLoader) {
             return {

package/dist/tools/v4/subagent/subagentFanout.js

@@ -122,6 +122,7 @@ function makeSubagentFanoutTool(factory) {
         category: 'network',
         mutates: false,
         toolset: 'subagent',
+        riskTier: 'caution', // v4.4 Phase 1
         async execute(args, _ctx) {
             const logger = factory.logger ?? (0, factory_1.noopLogger)();
             // ── Coerce args ────────────────────────────────────────────

package/dist/tools/v4/system/aidenSelfUpdate.js

@@ -68,6 +68,22 @@ exports.aidenSelfUpdateTool = {
     category: 'write',
     mutates: true,
     toolset: 'system',
+    riskTier: 'dangerous', // v4.4 Phase 1
+    // v4.4 Phase 4 — dry-run refuses; self-update bootstrapping is not
+    // safe to model with a no-op preview.
+    buildPreview(args) {
+        return {
+            tool: 'aiden_self_update',
+            args,
+            riskTier: 'dangerous',
+            sideEffects: [{
+                    type: 'refuse',
+                    reason: 'aiden_self_update is not safe to preview in dry-run mode. Set AIDEN_DRYRUN=0 to perform a real self-update (with the usual approval-engine confirmation).',
+                }],
+            detectedRisks: ['self_update'],
+            summary: 'Refused: aiden_self_update cannot be previewed in dry-run mode',
+        };
+    },
     async execute(args, ctx) {
         if (!ctx.paths) {
             return {

package/dist/tools/v4/system/appClose.js

@@ -53,6 +53,19 @@ exports.appCloseTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const app = typeof args.app === 'string' ? args.app : '';
+        const force = args.force === true;
+        return {
+            tool: 'app_close',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'app_control', action: force ? 'force-close' : 'close', target: app }],
+            detectedRisks: force ? ['force_close'] : [],
+            summary: `Would ${force ? 'force-' : ''}close app: ${app}`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)())
             return (0, _psHelpers_1.windowsOnlyError)('app_close');

package/dist/tools/v4/system/appInput.js

@@ -89,6 +89,19 @@ exports.appInputTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const app = typeof args.app === 'string' ? args.app : '';
+        const keys = typeof args.keys === 'string' ? args.keys : '';
+        return {
+            tool: 'app_input',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'app_control', action: `send-keys:${keys}`, target: app }],
+            detectedRisks: [],
+            summary: `Would send keys "${keys}" to app: ${app}`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)()) {
             return (0, _psHelpers_1.windowsOnlyError)('app_input', {

package/dist/tools/v4/system/appLaunch.js

@@ -123,6 +123,19 @@ exports.appLaunchTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const app = typeof args.app === 'string' ? args.app : '';
+        const cliArgs = Array.isArray(args.args) ? args.args.map(String) : [];
+        return {
+            tool: 'app_launch',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'app_control', action: 'launch', target: app + (cliArgs.length ? ' ' + cliArgs.join(' ') : '') }],
+            detectedRisks: [],
+            summary: `Would launch app: ${app}${cliArgs.length ? ' with args ' + cliArgs.join(' ') : ''}`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)())
             return (0, _psHelpers_1.windowsOnlyError)('app_launch');

package/dist/tools/v4/system/clipboardRead.js

@@ -32,6 +32,7 @@ exports.clipboardReadTool = {
     category: 'read',
     mutates: false,
     toolset: 'system',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(_args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)())
             return (0, _psHelpers_1.windowsOnlyError)('clipboard_read');

package/dist/tools/v4/system/clipboardWrite.js

@@ -19,6 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.clipboardWriteTool = void 0;
 const node_child_process_1 = require("node:child_process");
 const _psHelpers_1 = require("./_psHelpers");
+const dryRun_1 = require("../../../core/v4/dryRun");
 /**
  * Spawn `powershell.exe Set-Clipboard` with the text piped on stdin.
  * Wrapper Promise so the tool's `execute` can `await` it.
@@ -61,6 +62,19 @@ exports.clipboardWriteTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const text = typeof args.text === 'string' ? args.text : '';
+        const bytes = Buffer.byteLength(text, 'utf-8');
+        return {
+            tool: 'clipboard_write',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'clipboard_write', bytes, preview: (0, dryRun_1.truncatePreview)(text) }],
+            detectedRisks: [],
+            summary: `Would write ${bytes} bytes to clipboard`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)())
             return (0, _psHelpers_1.windowsOnlyError)('clipboard_write');

package/dist/tools/v4/system/mediaKey.js

@@ -53,6 +53,18 @@ exports.mediaKeyTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const action = typeof args.action === 'string' ? args.action : '';
+        return {
+            tool: 'media_key',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'media_control', action }],
+            detectedRisks: [],
+            summary: `Would send media key: ${action}`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)()) {
             return (0, _psHelpers_1.windowsOnlyError)('media_key', {

package/dist/tools/v4/system/mediaSessions.js

@@ -113,6 +113,7 @@ exports.mediaSessionsTool = {
     category: 'read',
     mutates: false,
     toolset: 'system',
+    riskTier: 'safe', // v4.4 Phase 1
     async execute(_args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)()) {
             return (0, _psHelpers_1.windowsOnlyError)('media_sessions', {

package/dist/tools/v4/system/mediaTransport.js

@@ -135,6 +135,19 @@ exports.mediaTransportTool = {
     category: 'execute',
     mutates: true,
     toolset: 'system',
+    riskTier: 'caution', // v4.4 Phase 1
+    buildPreview(args) {
+        const action = typeof args.action === 'string' ? args.action : '';
+        const target = typeof args.target === 'string' ? args.target : '';
+        return {
+            tool: 'media_transport',
+            args,
+            riskTier: 'caution',
+            sideEffects: [{ type: 'media_control', action: target ? `${action}:${target}` : action }],
+            detectedRisks: [],
+            summary: `Would invoke media transport: ${action}${target ? ` on ${target}` : ' (current session)'}`,
+        };
+    },
     async execute(args, _ctx) {
         if (!(0, _psHelpers_1.isWindows)()) {
             // v4.1.3-essentials: tailored capability card for non-Windows.