feat(v2): add pre-task script hook for scheduled tasks

Scheduled tasks can now carry a bash script that runs inside the container
before the agent is invoked. The script prints `{wakeAgent, data?}` on its
last stdout line; if `wakeAgent: false` (or the script errors) the task
row is marked completed and the agent is never queried, saving API calls
on no-op checks. On wake, the script's `data` is injected into the task
prompt. Semantics mirror V1: 30s bash timeout, 1MB buffer, last-line JSON,
error == skip.

Also blocks the Claude SDK's built-in scheduling tools (CronCreate,
CronDelete, CronList, ScheduleWakeup) via `disallowedTools` so tasks
actually flow through `mcp__nanoclaw__schedule_task` and get the script
gate. CLAUDE.md gains a soft pointer explaining why `schedule_task` is
the right path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

container/agent-runner/src/poll-loop.ts

@@ -4,6 +4,7 @@ import { writeMessageOut } from './db/messages-out.js';
 import { touchHeartbeat, clearStaleProcessingAcks } from './db/connection.js';
 import { getStoredSessionId, setStoredSessionId, clearStoredSessionId } from './db/session-state.js';
 import { formatMessages, extractRouting, categorizeMessage, type RoutingContext } from './formatter.js';
+import { applyPreTaskScripts } from './task-script.js';
 import type { AgentProvider, AgentQuery, ProviderEvent } from './providers/types.js';
 
 const POLL_INTERVAL_MS = 1000;
@@ -152,11 +153,25 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
       continue;
     }
 
+    // Pre-task scripts: for any task rows with a `script`, run it before the
+    // provider call. Scripts returning wakeAgent=false (or erroring) gate
+    // their own task row only — surviving messages still go to the agent.
+    const { keep, skipped } = await applyPreTaskScripts(normalMessages);
+    if (skipped.length > 0) {
+      markCompleted(skipped);
+      log(`Pre-task script skipped ${skipped.length} task(s): ${skipped.join(', ')}`);
+    }
+
+    if (keep.length === 0) {
+      log(`All ${normalMessages.length} non-command message(s) gated by script, skipping query`);
+      continue;
+    }
+
     // Format messages: passthrough commands get raw text (only if the
     // provider natively handles slash commands), others get XML.
-    const prompt = formatMessagesWithCommands(normalMessages, config.provider.supportsNativeSlashCommands);
+    const prompt = formatMessagesWithCommands(keep, config.provider.supportsNativeSlashCommands);
 
-    log(`Processing ${normalMessages.length} message(s), kinds: ${[...new Set(normalMessages.map((m) => m.kind))].join(',')}`);
+    log(`Processing ${keep.length} message(s), kinds: ${[...new Set(keep.map((m) => m.kind))].join(',')}`);
 
     const query = config.provider.query({
       prompt,
@@ -166,7 +181,8 @@ export async function runPollLoop(config: PollLoopConfig): Promise<void> {
     });
 
     // Process the query while concurrently polling for new messages
-    const processingIds = ids.filter((id) => !commandIds.includes(id));
+    const skippedSet = new Set(skipped);
+    const processingIds = ids.filter((id) => !commandIds.includes(id) && !skippedSet.has(id));
     try {
       const result = await processQuery(query, routing, config, processingIds);
       if (result.continuation && result.continuation !== continuation) {

container/agent-runner/src/providers/claude.ts

@@ -9,6 +9,11 @@ function log(msg: string): void {
   console.error(`[claude-provider] ${msg}`);
 }
 
+// Deferred SDK builtins that would sidestep nanoclaw's own scheduling.
+// Scheduling goes through mcp__nanoclaw__schedule_task so that tasks are
+// durable across sessions/restarts and gated by our pre-task script hook.
+const SDK_DISALLOWED_TOOLS = ['CronCreate', 'CronDelete', 'CronList', 'ScheduleWakeup'];
+
 // Tool allowlist for NanoClaw agent containers
 const TOOL_ALLOWLIST = [
   'Bash',
@@ -211,6 +216,7 @@ export class ClaudeProvider implements AgentProvider {
         resume: input.continuation,
         systemPrompt: instructions ? { type: 'preset' as const, preset: 'claude_code' as const, append: instructions } : undefined,
         allowedTools: TOOL_ALLOWLIST,
+        disallowedTools: SDK_DISALLOWED_TOOLS,
         env: this.env,
         permissionMode: 'bypassPermissions',
         allowDangerouslySkipPermissions: true,

container/agent-runner/src/task-script.ts

@@ -0,0 +1,121 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { MessageInRow } from './db/messages-in.js';
+import { touchHeartbeat } from './db/connection.js';
+
+const SCRIPT_TIMEOUT_MS = 30_000;
+const SCRIPT_MAX_BUFFER = 1024 * 1024;
+
+export interface ScriptResult {
+  wakeAgent: boolean;
+  data?: unknown;
+}
+
+function log(msg: string): void {
+  console.error(`[task-script] ${msg}`);
+}
+
+export async function runScript(script: string, taskId: string): Promise<ScriptResult | null> {
+  const scriptPath = path.join('/tmp', `task-script-${taskId}.sh`);
+  fs.writeFileSync(scriptPath, script, { mode: 0o755 });
+
+  return new Promise((resolve) => {
+    execFile(
+      'bash',
+      [scriptPath],
+      { timeout: SCRIPT_TIMEOUT_MS, maxBuffer: SCRIPT_MAX_BUFFER, env: process.env },
+      (error, stdout, stderr) => {
+        try {
+          fs.unlinkSync(scriptPath);
+        } catch {
+          /* best-effort cleanup */
+        }
+
+        if (stderr) {
+          log(`[${taskId}] stderr: ${stderr.slice(0, 500)}`);
+        }
+
+        if (error) {
+          log(`[${taskId}] error: ${error.message}`);
+          return resolve(null);
+        }
+
+        const lines = stdout.trim().split('\n');
+        const lastLine = lines[lines.length - 1];
+        if (!lastLine) {
+          log(`[${taskId}] no output`);
+          return resolve(null);
+        }
+
+        try {
+          const result = JSON.parse(lastLine);
+          if (typeof result.wakeAgent !== 'boolean') {
+            log(`[${taskId}] output missing wakeAgent boolean: ${lastLine.slice(0, 200)}`);
+            return resolve(null);
+          }
+          resolve(result as ScriptResult);
+        } catch {
+          log(`[${taskId}] output is not valid JSON: ${lastLine.slice(0, 200)}`);
+          resolve(null);
+        }
+      },
+    );
+  });
+}
+
+export interface TaskScriptOutcome {
+  keep: MessageInRow[];
+  skipped: string[];
+}
+
+/**
+ * Run pre-task scripts for any task messages that carry one, serially.
+ * - Errors / missing output / wakeAgent=false → task id added to `skipped`.
+ * - wakeAgent=true → content JSON is mutated to carry `scriptOutput`, so the
+ *   formatter renders it into the prompt.
+ * Non-task messages and tasks without scripts pass through unchanged.
+ */
+export async function applyPreTaskScripts(messages: MessageInRow[]): Promise<TaskScriptOutcome> {
+  const keep: MessageInRow[] = [];
+  const skipped: string[] = [];
+
+  for (const msg of messages) {
+    if (msg.kind !== 'task') {
+      keep.push(msg);
+      continue;
+    }
+
+    let content: Record<string, unknown>;
+    try {
+      content = JSON.parse(msg.content);
+    } catch {
+      keep.push(msg);
+      continue;
+    }
+
+    const script = typeof content.script === 'string' ? (content.script as string) : null;
+    if (!script) {
+      keep.push(msg);
+      continue;
+    }
+
+    log(`running script for task ${msg.id}`);
+    touchHeartbeat();
+    const result = await runScript(script, msg.id);
+    touchHeartbeat();
+
+    if (!result || !result.wakeAgent) {
+      const reason = result ? 'wakeAgent=false' : 'script error/no output';
+      log(`task ${msg.id} skipped: ${reason}`);
+      skipped.push(msg.id);
+      continue;
+    }
+
+    log(`task ${msg.id} wakeAgent=true, enriching prompt`);
+    content.scriptOutput = result.data ?? null;
+    keep.push({ ...msg, content: JSON.stringify(content) });
+  }
+
+  return { keep, skipped };
+}

groups/global/CLAUDE.md

@@ -126,7 +126,9 @@ request_rebuild({ reason: "Add memory MCP server" })
 
 ## Task Scripts
 
-For any recurring task, use `schedule_task`. Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
+For any recurring task, use `schedule_task`. This is the scheduling path — tasks persist across sessions and restarts, and support the pre-task `script` hook described below. Other scheduling tools you might discover (e.g. `CronCreate`, `ScheduleWakeup`) are session-scoped SDK builtins and won't behave the way NanoClaw users expect, so stick with `schedule_task`.
+
+Frequent agent invocations — especially multiple times a day — consume API credits and can risk account restrictions. If a simple check can determine whether action is needed, add a `script` — it runs first, and the agent is only called when the check passes. This keeps invocations to a minimum.
 
 ### How it works