talon-agent 5.30.0 → 5.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.30.0",
+  "version": "5.31.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",

package/prompts/system/agent-brief.md

@@ -50,7 +50,15 @@ never a substitute for `report_result`.
 
 {% if canSpawn %}You may spawn your own sub-agents with `spawn_agent` (current depth {{depth}}, cap {{maxDepth}}) when the work genuinely splits into independent pieces. You are then responsible for them: `wait_for_agent`, `send_to_agent`, `kill_agent`, and folding their reports into yours.{% else %}You are at the maximum sub-agent depth ({{maxDepth}}) — `spawn_agent` will be refused. Do this work yourself.{% endif %}
 
-## Boundaries
+{% if scratchDir %}## Scratch space
+
+Your private temp directory is `{{scratchDir}}` — `TMPDIR` points there for
+your shells and tools. Put scratch files, clones and build output there
+rather than in shared `/tmp`, where other agents are working. It is deleted
+when you finish successfully and kept if your run fails, so leave anything
+worth keeping somewhere permanent.
+
+{% endif %}## Boundaries
 
 - Do **not** message the user's chat directly unless the brief explicitly
   tells you to. Your report goes to the agent or chat that spawned you, and

package/src/backend/claude-sdk/one-shot.ts

@@ -91,6 +91,9 @@ export async function runOneShotAgent(
     systemPrompt,
     ...thinkingConfig,
     cwd: workspace,
+    // A sub-agent's private TMPDIR (and any other per-run vars), layered
+    // over the daemon's environment — the SDK replaces, not merges, `env`.
+    ...(params.env ? { env: { ...process.env, ...params.env } } : {}),
     permissionMode: "bypassPermissions" as const,
     allowDangerouslySkipPermissions: true,
     abortController,

package/src/core/agents/prompt.ts

@@ -40,8 +40,11 @@ export function buildAgentSystemPrompt(args: {
   parent: AgentParent;
   depth: number;
   maxDepth: number;
+  /** The agent's private TMPDIR, when one was created. */
+  scratchDir?: string;
 }): string {
   return loadSystemTemplate("agent-brief", {
+    scratchDir: args.scratchDir ?? "",
     agentId: args.agentId,
     label: args.label,
     parent: describeParent(args.parent),

package/src/core/agents/runner.ts

@@ -86,6 +86,7 @@ import { startWatchdog, type WatchdogHandle } from "./watchdog.js";
 import * as agentsRepo from "../../storage/agents/repo.js";
 import type { PersistedAgent } from "../../storage/agents/repo.js";
 import { agentRegistry } from "./registry.js";
+import { closeScratch, openScratch, scratchEnv } from "./scratch.js";
 import type {
   AgentCaps,
   AgentParent,
@@ -428,6 +429,7 @@ async function buildRunParams(
   abortController: AbortController,
   capture: { last: string },
   trail: RunTrail,
+  scratchDir: string | undefined,
   resume?: ResumePlan,
 ): Promise<OneShotAgentParams> {
   const writeLog = await openRunLog(
@@ -458,7 +460,9 @@ async function buildRunParams(
       parent: record.parent,
       depth: record.depth,
       maxDepth: capsHolder.caps.maxDepth,
+      ...(scratchDir ? { scratchDir } : {}),
     }),
+    ...(scratchDir ? { env: scratchEnv(scratchDir) } : {}),
     workspace: dirs.workspace,
     model,
     contextLabel: agentContextLabel(record.id),
@@ -623,6 +627,7 @@ async function runAgent(
 
   let settled: AgentRecord | null = null;
   try {
+    const scratchDir = await openScratch(id);
     const params = await buildRunParams(
       record,
       spec,
@@ -630,6 +635,7 @@ async function runAgent(
       abortController,
       capture,
       trail,
+      scratchDir,
       resume,
     );
     if (agentRegistry.isInterrupted(id)) {
@@ -708,6 +714,8 @@ async function runAgent(
     return;
   }
   if (!settled) return;
+  // Removed on success; kept on failure for whoever picks the work up.
+  await closeScratch(id, settled.state);
   log(
     "agents",
     `${id} "${settled.label}" → ${settled.state} ` +
@@ -802,6 +810,7 @@ async function settleRestored(
 ): Promise<void> {
   const settled = agentRegistry.settle(record.id, patch);
   if (!settled) return;
+  await closeScratch(record.id, settled.state);
   log(
     "agents",
     `${record.id} "${record.label}" → ${settled.state} (after restart)`,

package/src/core/agents/scratch.ts

@@ -0,0 +1,80 @@
+/**
+ * Scratch — a private temp directory per sub-agent.
+ *
+ * Every agent gets `/tmp/talon-agents/<id>/` (under `os.tmpdir()`), created
+ * when its run starts and exported as `TMPDIR` / `TMP` / `TEMP` to the
+ * backend run (`OneShotAgentParams.env`), so its shells and tools write
+ * their temporary files somewhere no other agent is writing. The directory
+ * is named in the agent's system prompt too, for backends that cannot take
+ * a per-run environment.
+ *
+ * Lifecycle: kept across a daemon restart (a resumed agent finds its files
+ * where it left them), removed when the agent settles `done`, and **kept**
+ * on any other terminal state so whoever picks up a failed, killed or
+ * timed-out run can inspect what it left behind.
+ */
+
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logWarn } from "../../util/log.js";
+import type { AgentState } from "./types.js";
+
+/** Root of every agent's scratch dir. Overridable for tests. */
+const root: { dir: string } = { dir: join(tmpdir(), "talon-agents") };
+
+export function setScratchRootForTest(dir: string): void {
+  root.dir = dir;
+}
+
+/** Absolute path of an agent's scratch dir (whether or not it exists). */
+export function agentScratchDir(agentId: string): string {
+  return join(root.dir, agentId);
+}
+
+/** The env a run with this scratch dir is given. */
+export function scratchEnv(dir: string): Record<string, string> {
+  return { TMPDIR: dir, TMP: dir, TEMP: dir };
+}
+
+/**
+ * Create (or reuse, on resume) the agent's scratch dir. Returns its path,
+ * or `undefined` when it could not be created — a run is never refused for
+ * want of a temp dir; it just shares the system one.
+ */
+export async function openScratch(
+  agentId: string,
+): Promise<string | undefined> {
+  const dir = agentScratchDir(agentId);
+  try {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  } catch (err) {
+    logWarn(
+      "agents",
+      `could not create scratch dir ${dir}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Clean up after a settled agent: removed on `done`, kept otherwise.
+ * Returns whether the directory was removed. Never throws.
+ */
+export async function closeScratch(
+  agentId: string,
+  state: AgentState,
+): Promise<boolean> {
+  if (state !== "done") return false;
+  try {
+    await rm(agentScratchDir(agentId), { recursive: true, force: true });
+    return true;
+  } catch (err) {
+    logWarn(
+      "agents",
+      `could not remove scratch dir for ${agentId}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return false;
+  }
+}

package/src/core/types.ts

@@ -187,6 +187,13 @@ export type OneShotAgentParams = {
    * `onAssistantText`: a throwing callback must never fail the run.
    */
   onSessionId?: (sessionId: string) => void;
+  /**
+   * Extra environment for the run's own subprocesses (shells, tools),
+   * layered over the daemon's. A sub-agent passes its private scratch dir
+   * as `TMPDIR` here. Honoured by the Claude SDK backend; backends whose
+   * subprocess environment is fixed per process ignore it.
+   */
+  env?: Readonly<Record<string, string>>;
 };
 
 /** How much cache telemetry a backend can surface in /status. */