@hyperdrive.bot/paseo-server 0.3.40 → 0.3.42

package/dist/server/server/agent/providers/claude/agent.js

@@ -24,7 +24,10 @@ import { normalizeProviderReplayTimestamp } from "../../provider-history-timesta
 import { composeSystemPromptParts } from "../../system-prompt.js";
 import { SdkTransport } from "./transport/sdk.js";
 import { PtyTransport } from "./transport/pty.js";
+import { resolvePaseoHome } from "../../../paseo-home.js";
 import { createPtySession } from "./pty-session-launcher.js";
+import { formatDenialMessage, isToolAllowed, parseToolAllowlist, } from "./tool-allowlist.js";
+import { removeGuardArtifacts, writeGuardArtifacts, } from "./tool-allowlist-guard.js";
 import { trackTransportSpawned } from "../../../monitoring/telemetry.js";
 import { isProviderImageMarkdown, materializeProviderImage, renderProviderImageOutputAsAssistantMarkdown, } from "../provider-image-output.js";
 import { getAgentStreamEventTurnId, } from "../../agent-sdk-types.js";
@@ -1111,6 +1114,9 @@ export class ClaudeAgentClient {
     constructor(options) {
         this.provider = "claude";
         this.capabilities = CLAUDE_CAPABILITIES;
+        // Enforced through a PreToolUse hook on both transports (SDK: options.hooks;
+        // PTY: a generated hook script registered via `claude --settings`).
+        this.supportsToolAllowlist = true;
         this.defaults = options.defaults;
         this.logger = options.logger.child({ module: "agent", provider: "claude" });
         this.runtimeSettings = options.runtimeSettings;
@@ -1575,11 +1581,34 @@ export class ClaudeAgentSession {
         this.emittedUserMessageIds = new Set();
         this.rewindTurnAnchors = [];
         this.pendingFreshSessionId = null;
+        /** PTY-transport guard files for the current session; removed on teardown. */
+        this.toolAllowGuard = null;
         this.cumulativeImageBase64Bytes = 0;
         this.cumulativeImageWarnEmitted = false;
         this.recentStderr = "";
         this.closed = false;
         this.hookEventHandlers = new Map();
+        /**
+         * SDK-transport half of allowlist enforcement. The PTY transport enforces the
+         * same rules through a generated hook script (see tool-allowlist-guard.ts);
+         * both call `isToolAllowed`, so the two transports cannot diverge.
+         */
+        this.enforceToolAllowlistHook = async (input) => {
+            if (input.hook_event_name !== "PreToolUse")
+                return {};
+            const toolName = input.tool_name;
+            if (isToolAllowed(toolName, input.tool_input, this.toolAllowRules))
+                return {};
+            const reason = formatDenialMessage(toolName, this.toolAllowRules);
+            this.logger.warn({ toolName }, "tool call blocked by run tool allowlist");
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: reason,
+                },
+            };
+        };
         this.handlePermissionRequest = async (toolName, input, options) => {
             const requestId = `permission-${randomUUID()}`;
             const kind = resolvePermissionKind(toolName, input);
@@ -1661,6 +1690,10 @@ export class ClaudeAgentSession {
         this.queryFactory = options.queryFactory;
         this.resolveBinary = options.resolveBinary;
         this.contextUsage = new ClaudeContextUsageState(findClaudeModel(this.config.model)?.contextWindowMaxTokens);
+        this.toolAllowRules = parseToolAllowlist(this.config.allowedTools ?? []);
+        if (this.toolAllowRules.length > 0) {
+            this.logger.info({ allowedTools: this.config.allowedTools }, "tool allowlist active: tools outside the list will be blocked before execution");
+        }
         const handle = options.handle;
         if (handle) {
             if (!handle.sessionId) {
@@ -2099,6 +2132,8 @@ export class ClaudeAgentSession {
             hasActiveForegroundTurnId: Boolean(this.activeForegroundTurnId),
         }, "provider.claude.session_close.start");
         this.closed = true;
+        removeGuardArtifacts(this.toolAllowGuard);
+        this.toolAllowGuard = null;
         this.rejectAllPendingPermissions(new Error("Claude session closed"));
         this.cancelCurrentTurn?.();
         this.subscribers.clear();
@@ -2559,6 +2594,7 @@ export class ClaudeAgentSession {
                 resume: Boolean(resumeId),
                 model: this.config.model,
                 permissionMode: this.currentMode,
+                ...this.refreshToolAllowGuard(ptySessionId),
                 appendSystemPrompt: this.buildAppendedSystemPrompt(),
                 input: input.iterable,
                 runtimeSettings: this.runtimeSettings,
@@ -2740,8 +2776,46 @@ export class ClaudeAgentSession {
                 ...this.runtimeSettings.disallowedTools,
             ];
         }
+        this.applyToolAllowlistHook(base);
         return base;
     }
+    /**
+     * Install the per-run tool allowlist as a `PreToolUse` hook on the SDK options.
+     *
+     * Deliberately NOT `options.allowedTools`: that field is a permission ALLOW rule
+     * (pre-approve, do not prompt), and this session also sets
+     * allowDangerouslySkipPermissions, under which permission rules are moot. A
+     * PreToolUse hook is the only gate that still fires; the SDK says so outright
+     * ("PreToolUse hook denies bypass canUseTool"). Applied last so an
+     * `extra.claude.hooks` override cannot displace it.
+     */
+    applyToolAllowlistHook(base) {
+        if (this.toolAllowRules.length === 0)
+            return;
+        const existing = base.hooks?.PreToolUse ?? [];
+        base.hooks = {
+            ...base.hooks,
+            PreToolUse: [...existing, { hooks: [this.enforceToolAllowlistHook] }],
+        };
+    }
+    /**
+     * PTY-transport half of allowlist enforcement: (re)generate the hook script and
+     * the `--settings` file that registers it.
+     *
+     * Returns a spreadable fragment (`{}` when no allowlist is configured) so the
+     * caller stays branch-free. Regenerated per spawn because a session can restart
+     * (mode swap, model swap, rewind) and the artifacts are keyed to the session id.
+     */
+    refreshToolAllowGuard(ptySessionId) {
+        removeGuardArtifacts(this.toolAllowGuard);
+        this.toolAllowGuard = writeGuardArtifacts({
+            rules: this.toolAllowRules,
+            sessionId: ptySessionId,
+            baseDir: resolvePaseoHome(),
+        });
+        const guard = this.toolAllowGuard;
+        return guard ? { settingsPath: guard.settingsPath } : {};
+    }
     buildSettingsOptions(extraClaudeOptions, input) {
         const fastMode = this.resolveFastModeSetting();
         if (fastMode === null && !input.ultracode) {

package/dist/server/server/agent/providers/claude/background-task-tracker.d.ts

@@ -27,9 +27,25 @@
  * output file's real birth time, reading the output back) is the caller's job.
  */
 export type ClaudeBackgroundTaskStatus = "running" | "completed" | "failed" | "canceled";
+/**
+ * What kind of background work a record represents. Surfaced so the UI can say
+ * WHAT is holding a session open ("pending · monitoring deploy.log") instead of
+ * an unexplained spinner, which is how users end up force-quitting sessions.
+ *
+ * ⚠️ Adding a member here is not enough to make it tracked — it must also get a
+ * start pattern above AND a retirement path, and be listed in the exhaustiveness
+ * test. See `background-work-kinds.ts`.
+ */
+export type ClaudeBackgroundTaskKind = "shell" | "monitor" | "cron";
+export interface BackgroundTaskStart {
+    id: string;
+    kind: ClaudeBackgroundTaskKind;
+}
 export interface ClaudeBackgroundTaskRecord {
     /** Harness-assigned shell id, e.g. `bjuk0pif4`. Stable across start and end. */
     id: string;
+    /** Which flavour of background work this is. Defaults to "shell" (legacy). */
+    kind: ClaudeBackgroundTaskKind;
     /** The shell command, from the originating `tool_use` input. Null if unseen. */
     command: string | null;
     /** The tool call's human description ("Run the test suite"), if it carried one. */
@@ -68,8 +84,29 @@ export declare function isTerminalTaskStatus(status: string | null | undefined):
  * terminal that isn't recognisably a failure or a cancel is a plain completion.
  */
 export declare function toTerminalRecordStatus(status: string | null | undefined): Exclude<ClaudeBackgroundTaskStatus, "running">;
-/** Extract every background-task id announced in a Bash tool_result's text. */
+/**
+ * Extract every background-task id announced in a Bash tool_result's text.
+ *
+ * Bash shells only — kept at this name and signature because it is part of the
+ * module's public surface. For all tracked kinds use
+ * {@link extractBackgroundTaskStarts}.
+ */
 export declare function extractBackgroundTaskIds(text: string | null | undefined): string[];
+/** Ids of monitors started in this text. */
+export declare function extractMonitorTaskIds(text: string | null | undefined): string[];
+/** Ids of cron jobs scheduled in this text. */
+export declare function extractCronTaskIds(text: string | null | undefined): string[];
+/** Ids of cron jobs cancelled in this text (a cron's only retirement signal). */
+export declare function extractCancelledCronTaskIds(text: string | null | undefined): string[];
+/**
+ * Every background-work start announced in one tool_result, tagged by kind.
+ *
+ * This is the single place that decides "does this text start something that
+ * keeps the agent alive?". A new kind of background work is invisible until it
+ * is added HERE — which is precisely how monitors and crons went untracked
+ * while `deriveAgentStateBucket` happily reported those sessions as done.
+ */
+export declare function extractBackgroundTaskStarts(text: string | null | undefined): BackgroundTaskStart[];
 /** Extract the output-file path the harness announced alongside the id, if any. */
 export declare function extractBackgroundOutputFile(text: string | null | undefined): string | null;
 export declare class ClaudeBackgroundTaskTracker {

package/dist/server/server/agent/providers/claude/background-task-tracker.js

@@ -47,6 +47,45 @@ const BACKGROUND_ID_PATTERN = /Command running in background with ID:\s*([A-Za-z
  * path from the id (the directory is session-scoped and not derivable here).
  */
 const OUTPUT_FILE_PATTERN = /Output is being written to:\s*(\S+)/;
+/**
+ * Matches the harness line for a started **Monitor** (the long-running watcher
+ * tool), which announces itself with a completely different sentence from a
+ * backgrounded Bash:
+ *
+ *   Monitor started (task b6dxcqe9y, timeout 20000ms). You will be notified on
+ *   each event. Keep working — do not poll or sleep.
+ *
+ * The id is followed by a comma rather than a period, so it needs its own
+ * capture. Crucially the monitor's END is already handled: it retires through
+ * the SAME `<task-notification>` envelope carrying the same `<task-id>` and a
+ * `<status>completed</status>`. Only the start was invisible, which is why a
+ * session holding a live monitor reported zero background tasks and settled to
+ * "done" while the monitor was still watching.
+ *
+ * Captured verbatim from a live session on 2026-08-22, not transcribed.
+ */
+const MONITOR_ID_PATTERN = /Monitor started \(task\s+([A-Za-z0-9._-]+)/g;
+/**
+ * Matches a scheduled **cron** job's announcement. Two shapes, one per mode:
+ *
+ *   Scheduled one-shot task dcdae8f2 (17 4 1 1 *). Session-only ...
+ *   Scheduled recurring job b8df03d3 (Every Wednesday at 4:23 AM). Session-only ...
+ *
+ * Note the noun changes with the mode ("task" vs "job"), so both are accepted.
+ * Captured verbatim from a live session on 2026-08-22.
+ */
+const CRON_ID_PATTERN = /Scheduled\s+(?:one-shot|recurring)\s+(?:task|job)\s+([A-Za-z0-9._-]+)/g;
+/**
+ * Matches a cancelled cron job. A cron has no `<task-notification>`, so this
+ * tool_result line is its ONLY retirement signal:
+ *
+ *   Cancelled job b8df03d3.
+ *
+ * The trailing period is glued to the id — the exact defect class documented in
+ * {@link stripTrailingSentencePunctuation}. It is stripped, or the id would
+ * never match the record and the agent would sit in "pending" forever.
+ */
+const CRON_CANCEL_PATTERN = /Cancelled job\s+([A-Za-z0-9._-]+)/g;
 /**
  * Trim the sentence punctuation the harness's prose leaves glued to a capture.
  *
@@ -109,24 +148,66 @@ export function toTerminalRecordStatus(status) {
     }
     return "completed";
 }
-/** Extract every background-task id announced in a Bash tool_result's text. */
-export function extractBackgroundTaskIds(text) {
+/**
+ * Run one module-scoped global pattern over `text` and return every stripped
+ * capture. Shared by all start/cancel scanners so the two easy-to-forget
+ * details — resetting `lastIndex` on a module-scoped global regex, and
+ * stripping the sentence punctuation the harness's prose glues to a capture —
+ * are written once instead of per pattern.
+ */
+function scanIds(pattern, text) {
     if (typeof text !== "string" || text.length === 0) {
         return [];
     }
     const ids = [];
-    // Reset lastIndex defensively — the regex is module-scoped and global.
-    BACKGROUND_ID_PATTERN.lastIndex = 0;
-    let match = BACKGROUND_ID_PATTERN.exec(text);
+    pattern.lastIndex = 0;
+    let match = pattern.exec(text);
     while (match !== null) {
         const id = match[1] ? stripTrailingSentencePunctuation(match[1]) : "";
         if (id) {
             ids.push(id);
         }
-        match = BACKGROUND_ID_PATTERN.exec(text);
+        match = pattern.exec(text);
     }
     return ids;
 }
+/**
+ * Extract every background-task id announced in a Bash tool_result's text.
+ *
+ * Bash shells only — kept at this name and signature because it is part of the
+ * module's public surface. For all tracked kinds use
+ * {@link extractBackgroundTaskStarts}.
+ */
+export function extractBackgroundTaskIds(text) {
+    return scanIds(BACKGROUND_ID_PATTERN, text);
+}
+/** Ids of monitors started in this text. */
+export function extractMonitorTaskIds(text) {
+    return scanIds(MONITOR_ID_PATTERN, text);
+}
+/** Ids of cron jobs scheduled in this text. */
+export function extractCronTaskIds(text) {
+    return scanIds(CRON_ID_PATTERN, text);
+}
+/** Ids of cron jobs cancelled in this text (a cron's only retirement signal). */
+export function extractCancelledCronTaskIds(text) {
+    return scanIds(CRON_CANCEL_PATTERN, text);
+}
+/**
+ * Every background-work start announced in one tool_result, tagged by kind.
+ *
+ * This is the single place that decides "does this text start something that
+ * keeps the agent alive?". A new kind of background work is invisible until it
+ * is added HERE — which is precisely how monitors and crons went untracked
+ * while `deriveAgentStateBucket` happily reported those sessions as done.
+ */
+export function extractBackgroundTaskStarts(text) {
+    return [
+        ...extractBackgroundTaskIds(text).map((id) => ({ id, kind: "shell" })),
+        ...extractMonitorTaskIds(text).map((id) => ({ id, kind: "monitor" })),
+        ...extractCronTaskIds(text).map((id) => ({ id, kind: "cron" })),
+    ];
+}
 /** Extract the output-file path the harness announced alongside the id, if any. */
 export function extractBackgroundOutputFile(text) {
     if (typeof text !== "string" || text.length === 0) {
@@ -158,15 +239,19 @@ export class ClaudeBackgroundTaskTracker {
         const outputFile = extractBackgroundOutputFile(normalized.text);
         const startedAt = normalized.startedAt ?? new Date().toISOString();
         const added = [];
-        for (const id of extractBackgroundTaskIds(normalized.text)) {
+        for (const { id, kind } of extractBackgroundTaskStarts(normalized.text)) {
             if (this.running.has(id)) {
                 continue;
             }
             this.running.set(id, {
                 id,
+                kind,
                 command: normalized.command ?? null,
                 description: normalized.description ?? null,
-                outputFile,
+                // Only a backgrounded shell announces an output file on START. A
+                // monitor announces its own on its terminal notification instead, and a
+                // cron never has one.
+                outputFile: kind === "shell" ? outputFile : null,
                 startedAt,
                 endedAt: null,
                 status: "running",
@@ -174,6 +259,22 @@ export class ClaudeBackgroundTaskTracker {
             });
             added.push(id);
         }
+        // A cron has no `<task-notification>`, so its cancellation arrives as
+        // another tool_result in this same stream. Retire it here or it stays live
+        // forever and pins the agent to "pending" — the "never retires" failure
+        // this module already documents for a mis-captured shell id.
+        for (const id of extractCancelledCronTaskIds(normalized.text)) {
+            const record = this.running.get(id);
+            if (!record || record.kind !== "cron") {
+                continue;
+            }
+            this.running.delete(id);
+            this.retire({
+                ...record,
+                status: "canceled",
+                endedAt: new Date().toISOString(),
+            });
+        }
         return added;
     }
     /**
@@ -211,7 +312,11 @@ export class ClaudeBackgroundTaskTracker {
             return false;
         }
         this.running.delete(taskId);
-        this.retire({ ...record, status: "canceled", endedAt: new Date().toISOString() });
+        this.retire({
+            ...record,
+            status: "canceled",
+            endedAt: new Date().toISOString(),
+        });
         return true;
     }
     has(taskId) {

package/dist/server/server/agent/providers/claude/background-work-kinds.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The complete census of background work a Claude Code session can hold open.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * `deriveAgentStateBucket` ends in `return "done"`. That makes "done" the
+ * FALLTHROUGH: any kind of background work nobody taught the system about
+ * becomes invisible by construction, not by decision. Monitors and crons sat in
+ * that blind spot for the life of the feature — a session with an armed monitor
+ * reported zero background tasks, bucketed as "done", and looked idle while it
+ * was actively watching.
+ *
+ * The fix is not "remember to add a pattern". It is to enumerate what we
+ * SILENCE rather than what we want, so an unlisted kind is merely noisy (a
+ * failing build) instead of invisible (a lying UI).
+ *
+ * HOW IT FAILS LOUDLY
+ *
+ * `BACKGROUND_WORK_KINDS` is declared `satisfies Record<BackgroundWorkKind, …>`.
+ * Add a member to the union without adding its entry here and the TYPE CHECK
+ * fails. Add an entry claiming `tracked: true` without a start pattern that
+ * actually extracts its id and `background-work-kinds.test.ts` fails.
+ *
+ * SAMPLES ARE CAPTURES, NOT TRANSCRIPTIONS
+ *
+ * Every `sample` below was pasted verbatim out of a live session's tool_result
+ * on 2026-08-22. Do not tidy them. This repo has already shipped a regex that
+ * passed 21 green tests against hand-typed fixtures while being broken in
+ * production, because the real text was prose and every fixture was a clean
+ * one-liner. If you add a kind, capture its real string first.
+ */
+/** Every flavour of background work, tracked or deliberately not. */
+export type BackgroundWorkKind = "shell" | "monitor" | "cron" | "scheduled_wakeup" | "subagent";
+interface TrackedKind {
+    tracked: true;
+    /** Human label for the UI ("pending · monitoring deploy.log"). */
+    label: string;
+    /** Verbatim capture of the harness text that announces a start. */
+    sample: string;
+    /** The id the sample must yield, proving the pattern actually works. */
+    expectedId: string;
+    /** Where the record is retired. */
+    retiredBy: string;
+    /** Which module owns the tracking. */
+    trackedBy: string;
+}
+interface SilencedKind {
+    tracked: false;
+    label: string;
+    /**
+     * Why this kind does NOT keep an agent alive. Must be a real, specific
+     * reason — "not implemented yet" is one, and an honest one. What is not
+     * allowed is for a kind to be absent from this file entirely.
+     */
+    silencedBecause: string;
+}
+export type BackgroundWorkKindEntry = TrackedKind | SilencedKind;
+export declare const BACKGROUND_WORK_KINDS: {
+    readonly shell: {
+        readonly tracked: true;
+        readonly label: "background shell";
+        readonly sample: "Command running in background with ID: beuhoixae. Output is being written to: /tmp/x/beuhoixae.output. You will be notified when it completes.";
+        readonly expectedId: "beuhoixae";
+        readonly retiredBy: "<task-notification> with a terminal <status>";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly monitor: {
+        readonly tracked: true;
+        readonly label: "monitor";
+        readonly sample: "Monitor started (task b6dxcqe9y, timeout 20000ms). You will be notified on each event. Keep working — do not poll or sleep.";
+        readonly expectedId: "b6dxcqe9y";
+        readonly retiredBy: "<task-notification> with a terminal <status>";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly cron: {
+        readonly tracked: true;
+        readonly label: "scheduled job";
+        readonly sample: "Scheduled recurring job b8df03d3 (Every Wednesday at 4:23 AM). Session-only (not written to disk, dies when Claude exits). Auto-expires after 7 days. Use CronDelete to cancel sooner.";
+        readonly expectedId: "b8df03d3";
+        readonly retiredBy: "\"Cancelled job <id>.\" in a later tool_result";
+        readonly trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText";
+    };
+    readonly scheduled_wakeup: {
+        readonly tracked: false;
+        readonly label: "scheduled wakeup";
+        readonly silencedBecause: "ScheduleWakeup only exists inside /loop dynamic mode, and invoking it to capture its announcement would schedule a real wakeup of the capturing session. No verbatim capture has been taken yet, and this module's rule is that a pattern is written from a real string or not at all. A /loop session's transcript must be captured before this can move to tracked:true. Until then a dynamic /loop between wakeups buckets as done.";
+    };
+    readonly subagent: {
+        readonly tracked: false;
+        readonly label: "subagent";
+        readonly silencedBecause: "Live subagents DO keep the parent alive, but not through this tracker: they arrive as their own agent snapshots and are attributed to the delegation root in workspace-directory.applyAgentBucketContributions (server) and countActiveChildrenByParent (app). Counting them here as well would double-count them.";
+    };
+};
+export {};
+//# sourceMappingURL=background-work-kinds.d.ts.map

package/dist/server/server/agent/providers/claude/background-work-kinds.js

@@ -0,0 +1,73 @@
+/**
+ * The complete census of background work a Claude Code session can hold open.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * `deriveAgentStateBucket` ends in `return "done"`. That makes "done" the
+ * FALLTHROUGH: any kind of background work nobody taught the system about
+ * becomes invisible by construction, not by decision. Monitors and crons sat in
+ * that blind spot for the life of the feature — a session with an armed monitor
+ * reported zero background tasks, bucketed as "done", and looked idle while it
+ * was actively watching.
+ *
+ * The fix is not "remember to add a pattern". It is to enumerate what we
+ * SILENCE rather than what we want, so an unlisted kind is merely noisy (a
+ * failing build) instead of invisible (a lying UI).
+ *
+ * HOW IT FAILS LOUDLY
+ *
+ * `BACKGROUND_WORK_KINDS` is declared `satisfies Record<BackgroundWorkKind, …>`.
+ * Add a member to the union without adding its entry here and the TYPE CHECK
+ * fails. Add an entry claiming `tracked: true` without a start pattern that
+ * actually extracts its id and `background-work-kinds.test.ts` fails.
+ *
+ * SAMPLES ARE CAPTURES, NOT TRANSCRIPTIONS
+ *
+ * Every `sample` below was pasted verbatim out of a live session's tool_result
+ * on 2026-08-22. Do not tidy them. This repo has already shipped a regex that
+ * passed 21 green tests against hand-typed fixtures while being broken in
+ * production, because the real text was prose and every fixture was a clean
+ * one-liner. If you add a kind, capture its real string first.
+ */
+export const BACKGROUND_WORK_KINDS = {
+    shell: {
+        tracked: true,
+        label: "background shell",
+        sample: "Command running in background with ID: beuhoixae. Output is being written to: /tmp/x/beuhoixae.output. You will be notified when it completes.",
+        expectedId: "beuhoixae",
+        retiredBy: "<task-notification> with a terminal <status>",
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    monitor: {
+        tracked: true,
+        label: "monitor",
+        sample: "Monitor started (task b6dxcqe9y, timeout 20000ms). You will be notified on each event. Keep working — do not poll or sleep.",
+        expectedId: "b6dxcqe9y",
+        // Confirmed live: the monitor's completion arrives as the SAME
+        // <task-notification> envelope, same <task-id>, <status>completed</status>.
+        // Only its START was ever invisible.
+        retiredBy: "<task-notification> with a terminal <status>",
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    cron: {
+        tracked: true,
+        label: "scheduled job",
+        sample: "Scheduled recurring job b8df03d3 (Every Wednesday at 4:23 AM). Session-only (not written to disk, dies when Claude exits). Auto-expires after 7 days. Use CronDelete to cancel sooner.",
+        expectedId: "b8df03d3",
+        // A cron emits NO task-notification. "Cancelled job <id>." in a later
+        // tool_result is its only retirement signal — note the glued-on period.
+        retiredBy: '"Cancelled job <id>." in a later tool_result',
+        trackedBy: "ClaudeBackgroundTaskTracker.noteToolResultText",
+    },
+    scheduled_wakeup: {
+        tracked: false,
+        label: "scheduled wakeup",
+        silencedBecause: "ScheduleWakeup only exists inside /loop dynamic mode, and invoking it to capture its announcement would schedule a real wakeup of the capturing session. No verbatim capture has been taken yet, and this module's rule is that a pattern is written from a real string or not at all. A /loop session's transcript must be captured before this can move to tracked:true. Until then a dynamic /loop between wakeups buckets as done.",
+    },
+    subagent: {
+        tracked: false,
+        label: "subagent",
+        silencedBecause: "Live subagents DO keep the parent alive, but not through this tracker: they arrive as their own agent snapshots and are attributed to the delegation root in workspace-directory.applyAgentBucketContributions (server) and countActiveChildrenByParent (app). Counting them here as well would double-count them.",
+    },
+};
+//# sourceMappingURL=background-work-kinds.js.map

package/dist/server/server/agent/providers/claude/pty-session-launcher.d.ts

@@ -11,6 +11,13 @@ export interface CreatePtySessionOptions {
     resume: boolean;
     model?: string;
     permissionMode: string;
+    /**
+     * Extra settings file passed as `claude --settings <path>`. Used to install the
+     * per-run tool-allowlist PreToolUse hook (see tool-allowlist-guard.ts). `--settings`
+     * LAYERS onto the user/project/local settings claude already reads, so this adds the
+     * guard without displacing anything the user configured.
+     */
+    settingsPath?: string;
     appendSystemPrompt?: string;
     /** The shared input channel fed by startTurn() — PtyQuery types these into the PTY. */
     input: AsyncIterable<SDKUserMessage>;

package/dist/server/server/agent/providers/claude/pty-session-launcher.js

@@ -47,6 +47,9 @@ export async function createPtySession(opts) {
         cwd: realCwd,
         env,
         dims: opts.dims ?? DEFAULT_DIMS,
+        // Names the tmux session deterministically when PASEO_PTY_TMUX=1, so a daemon restart
+        // reattaches this agent rather than spawning a second one alongside it.
+        sessionId: opts.sessionId,
         ...(systemPromptFilePath ? { systemPromptFilePath } : {}),
     });
     const query = new PtyQuery({
@@ -70,6 +73,12 @@ function buildInteractiveFlags(opts) {
     if (opts.permissionMode)
         flags.push("--permission-mode", opts.permissionMode);
     flags.push("--dangerously-skip-permissions");
+    // Order matters only for readability; claude merges --settings over its own sources.
+    // The tool allowlist rides here BECAUSE of the line above: --dangerously-skip-permissions
+    // neutralizes every permission rule, and a PreToolUse hook is the one gate it does not
+    // skip. Verified on claude 2.1.239.
+    if (opts.settingsPath)
+        flags.push("--settings", opts.settingsPath);
     // Inject the same MCP servers the SDK path passes (incl. the paseo MCP) so the PTY agent
     // keeps its mcp__paseo__* tools (create_agent, terminals, schedules…). claude accepts
     // --mcp-config as an inline JSON string. Without this, orchestrated agents (the pool /

package/dist/server/server/agent/providers/claude/tool-allowlist-guard.d.ts

@@ -0,0 +1,41 @@
+import { type ToolAllowRule } from "./tool-allowlist.js";
+/**
+ * Materializes the PTY-transport half of tool-allowlist enforcement: a
+ * `PreToolUse` hook script plus the `--settings` file that registers it.
+ *
+ * The SDK transport enforces the same allowlist in-process (an `options.hooks`
+ * callback). The PTY transport spawns a real `claude` terminal, so its gate has
+ * to be a command on disk.
+ *
+ * SINGLE SOURCE OF TRUTH: the guard script is generated by serializing the very
+ * functions the in-process path calls (`Function.prototype.toString()`), so the
+ * two transports cannot drift into enforcing different rules. `tool-allowlist-guard.test.ts`
+ * executes the generated script over the same fixture table that exercises
+ * `isToolAllowed()` to keep that guarantee honest. Neither the tsc build nor tsx
+ * minifies, so the emitted bodies are valid, type-free JS in dev and in dist.
+ */
+export interface GuardArtifacts {
+    /** Directory holding both generated files. Delete it on session teardown. */
+    readonly dir: string;
+    /** Path passed to `claude --settings`. */
+    readonly settingsPath: string;
+    /** Path of the generated hook script. */
+    readonly guardPath: string;
+}
+/** The standalone `PreToolUse` hook script, with the rules baked in. */
+export declare function buildGuardScript(rules: readonly ToolAllowRule[]): string;
+/** The `--settings` payload that registers the guard for every tool call. */
+export declare function buildGuardSettings(nodeBinary: string, guardPath: string): string;
+/**
+ * Write the guard script + settings file for a session. Returns null when the
+ * allowlist is empty, i.e. no allowlist was configured and nothing is enforced.
+ */
+export declare function writeGuardArtifacts(options: {
+    readonly rules: readonly ToolAllowRule[];
+    readonly sessionId: string;
+    readonly baseDir: string;
+    readonly nodeBinary?: string;
+}): GuardArtifacts | null;
+/** Best-effort teardown for `writeGuardArtifacts`. */
+export declare function removeGuardArtifacts(artifacts: GuardArtifacts | null | undefined): void;
+//# sourceMappingURL=tool-allowlist-guard.d.ts.map