@akira-tl/forgerelay 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.5.6] - 2026-08-17
+
+### Fixed
+
+- Repaired historical `bash_output_streams` SQLite schemas that had already recorded the Bash audit migration before later audit columns were added, preventing Bash completion from crashing ForgeRelay with `no such column: error` and avoiding ambiguous Host timeouts after commands had already executed.
+- Made the background-completion retention regression wait for the process to actually finish before crossing its retention window, removing a Windows-only timing race from the release suite.
+
+### Changed
+
+- The `release-tag-local-ci` Hook now runs the full cloud-equivalent verification surface on an isolated Node 22.19 / npm 10.9.3 checkout before allowing a stable tag push, instead of only checking a previously recorded proof whose parity suite could omit server-level tests.
+
+## [0.5.5] - 2026-08-15
+
+### Added
+
+- Added native multi-target `read`, `edit`, and `delete` operations so Agents can read several files or apply one validated edit/delete intent across multiple paths in a single interaction; bulk mutations preflight every target before the first filesystem change and report mutation-phase partial failures without claiming transactional rollback.
+- Added the `batch.execute` capability for 1–100 heterogeneous Read/Write/Edit/Rename/Delete/Bash/Capability tasks with caller-controlled concurrency from 1–10, stable input-order results, continue-on-error execution, conflict-aware scheduling, conservative Bash/serial-Capability exclusivity, and Host cancellation that never invents Activities for queued work that did not start.
+- Added durable parent/child Activity relationships and aggregate summaries for native bulk and Batch execution, while preserving lazy child detail, compact Bash responses plus stable `outputId`, and restart-safe local audit/query behavior.
+
+### Changed
+
+- Capability definitions now declare and advertise an explicit Batch policy (`parallel`, `serial`, or `unsupported`); `hooks.check` and `code.intelligence` are parallel, `review.changes` is serial, while Host-native artifact download and recursive `batch.execute` use are unsupported inside a Batch.
+- Core work operations now share one internal execution seam so single MCP calls and Batch children use the same path validation, Hooks, Activity lifecycle, logging, cancellation, and result semantics instead of duplicating tool handlers.
+
 ## [0.5.4] - 2026-08-15
 
 ### Fixed

package/capabilities/batch-execution/GUIDE.md

@@ -0,0 +1,18 @@
+# Batch execution
+
+Use `capability` with `name="batch.execute"` when several independent ForgeRelay core operations can be completed in one Agent interaction.
+
+## Contract
+
+- Every batch belongs to one already-open `workspaceId`.
+- Supply 1–100 tasks. Every task requires a unique stable `id`.
+- Supported operations are `read`, `write`, `edit`, `rename`, `delete`, `bash.run`, and `capability.run`.
+- Core tasks are single-target operations. Use native `read(paths)`, `edit(paths)`, or `delete(paths)` for one homogeneous operation over multiple targets instead of nesting bulk groups inside a batch.
+- `concurrency` may be 1–10. When omitted, ForgeRelay uses `min(task count, 10)`.
+- Independent tasks may run concurrently. Conflicting filesystem mutations are serialized automatically. `bash.run` is treated conservatively as exclusive work because a shell command may modify arbitrary workspace state.
+- Capability definitions explicitly advertise a batch policy: `parallel`, `serial`, or `unsupported`. Parallel capabilities may run concurrently; serial capabilities run exclusively in v0.5.5; unsupported capabilities return a task-level error while preserving the failed child Activity.
+- One task failure does not stop independent tasks. Results are returned in the same order as the input task list.
+- Host cancellation stops launching queued tasks and is propagated to already-running tasks.
+- Batch execution does not support nested batches, Workspace lifecycle calls, Activity query/control calls, or Bash process-control actions.
+
+Each actual task retains its normal ForgeRelay Hooks, Activity audit, validation, and result semantics. The Batch parent is an aggregate Activity and does not execute Tool Hooks itself.

package/dist/activity/audit-store.js

@@ -14,6 +14,15 @@ export class ActivityAuditStore {
                 if (existing.length > 0) {
                     throw new Error(`Activity ${input.activityId} already has audit events.`);
                 }
+                if (input.parentActivityId) {
+                    const parent = this.getActivity(input.parentActivityId);
+                    if (!parent) {
+                        throw new Error(`Unknown parent Activity: ${input.parentActivityId}.`);
+                    }
+                    if (parent.turnId !== input.turnId) {
+                        throw new Error(`Parent Activity ${input.parentActivityId} belongs to Host Turn ${parent.turnId}, not ${input.turnId}.`);
+                    }
+                }
             }
             else if (existing.length === 0 || existing[0]?.event_type !== "started") {
                 throw new Error(`Activity ${input.activityId} must start before recording ${input.type}.`);
@@ -28,6 +37,7 @@ export class ActivityAuditStore {
           sequence,
           event_type,
           turn_id,
+          parent_activity_id,
           conversation_scope_id,
           tool,
           workspace_id,
@@ -40,7 +50,7 @@ export class ActivityAuditStore {
           result_json,
           error,
           created_at
-        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.activity_id, row.sequence, row.event_type, row.turn_id, row.conversation_scope_id, row.tool, row.workspace_id, row.workspace_root, row.workspace_mode, row.workspace_source_root, row.workspace_branch, row.workspace_target_branch, row.request_json, row.result_json, row.error, row.created_at);
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.activity_id, row.sequence, row.event_type, row.turn_id, row.parent_activity_id, row.conversation_scope_id, row.tool, row.workspace_id, row.workspace_root, row.workspace_mode, row.workspace_source_root, row.workspace_branch, row.workspace_target_branch, row.request_json, row.result_json, row.error, row.created_at);
             return rowToEvent(row);
         })();
     }
@@ -104,6 +114,7 @@ export class ActivityAuditStore {
         return {
             activityId: started.activityId,
             turnId: started.turnId,
+            ...(started.parentActivityId ? { parentActivityId: started.parentActivityId } : {}),
             ...(started.conversationScopeId ? { conversationScopeId: started.conversationScopeId } : {}),
             tool: started.tool,
             workspace: started.workspace,
@@ -132,6 +143,7 @@ function eventInputToRow(input, identity) {
             sequence: identity.sequence,
             event_type: input.type,
             turn_id: input.turnId,
+            parent_activity_id: input.parentActivityId ?? null,
             conversation_scope_id: input.conversationScopeId ?? null,
             tool: input.tool,
             workspace_id: input.workspace.id ?? null,
@@ -152,6 +164,7 @@ function eventInputToRow(input, identity) {
         sequence: identity.sequence,
         event_type: input.type,
         turn_id: null,
+        parent_activity_id: null,
         conversation_scope_id: null,
         tool: null,
         workspace_id: null,
@@ -182,6 +195,7 @@ function rowToEvent(row) {
                 ...base,
                 type: "started",
                 turnId: row.turn_id,
+                ...(row.parent_activity_id ? { parentActivityId: row.parent_activity_id } : {}),
                 ...(row.conversation_scope_id ? { conversationScopeId: row.conversation_scope_id } : {}),
                 tool: row.tool,
                 workspace: {

package/dist/activity/lifecycle.js

@@ -53,6 +53,7 @@ export class ActivityLifecycle {
             type: "started",
             activityId,
             turnId,
+            ...(options.parentActivityId ? { parentActivityId: options.parentActivityId } : {}),
             ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
             tool: options.tool,
             workspace: options.workspace,
@@ -61,6 +62,7 @@ export class ActivityLifecycle {
         return {
             activityId,
             turnId,
+            ...(options.parentActivityId ? { parentActivityId: options.parentActivityId } : {}),
             ...(options.conversationScopeId ? { conversationScopeId: options.conversationScopeId } : {}),
         };
     }

package/dist/activity/query-service.js

@@ -17,7 +17,7 @@ export class ActivityQueryService {
     snapshot(turnId, knownRevision) {
         this.requireTurn(turnId);
         const revision = this.audit.turnRevision(turnId);
-        const activities = this.audit.listActivitiesByTurn(turnId).map(toSummary);
+        const activities = this.summaries(turnId);
         const state = aggregateState(activities);
         const changed = knownRevision === undefined || knownRevision !== revision;
         return {
@@ -34,7 +34,8 @@ export class ActivityQueryService {
         if (!record || record.turnId !== turnId) {
             throw new Error(`Unknown Activity ${activityId} in Host Turn ${turnId}.`);
         }
-        const activity = toSummary(record);
+        const activity = this.summaries(turnId)
+            .find((summary) => summary.activityId === activityId) ?? toSummary(record);
         if (!activity.detailAvailable) {
             throw new Error(`Activity ${activityId} is summary-complete and has no lazy detail.`);
         }
@@ -69,6 +70,30 @@ export class ActivityQueryService {
             ...(output.finishedAt !== undefined ? { finishedAt: output.finishedAt } : {}),
         };
     }
+    summaries(turnId) {
+        const records = this.audit.listActivitiesByTurn(turnId);
+        const summaries = records.map(toSummary);
+        const children = new Map();
+        for (const summary of summaries) {
+            if (!summary.parentActivityId)
+                continue;
+            const aggregate = children.get(summary.parentActivityId) ?? {
+                total: 0,
+                working: 0,
+                done: 0,
+                error: 0,
+            };
+            aggregate.total += 1;
+            aggregate[summary.status] += 1;
+            children.set(summary.parentActivityId, aggregate);
+        }
+        return summaries.map((summary) => {
+            const aggregate = children.get(summary.activityId);
+            return aggregate
+                ? { ...summary, detailAvailable: false, children: aggregate }
+                : summary;
+        });
+    }
     requireTurn(turnId) {
         if (!this.turns.get(turnId))
             throw new Error(`Unknown Host Turn: ${turnId}.`);
@@ -88,15 +113,18 @@ function toSummary(record) {
         ?? numberField(result, "wallTimeMs")
         ?? elapsedMs(record.startedAt, record.updatedAt, record.state);
     const bashLike = record.tool === "bash" || record.tool === "exec_command" || record.tool === "bash_result";
+    const bulkGroup = arrayField(request, "paths") !== undefined &&
+        (record.tool === "read" || record.tool === "edit" || record.tool === "delete");
     return {
         activityId: record.activityId,
+        ...(record.parentActivityId ? { parentActivityId: record.parentActivityId } : {}),
         tool: record.tool,
         kind: activityKind(record.tool),
         status: activityStatus(record.state),
         state: record.state,
         title: activityTitle(record.tool),
         target: activityTarget(record, request, result, structured),
-        detailAvailable: record.tool !== "rename" && record.tool !== "delete",
+        detailAvailable: !bulkGroup && record.tool !== "rename" && record.tool !== "delete" && record.tool !== "batch",
         ...(record.workspace.id ? { workspaceId: record.workspace.id } : {}),
         ...(processId !== undefined ? { processId } : {}),
         ...(outputId !== undefined ? { outputId } : {}),
@@ -124,6 +152,8 @@ function activityKind(tool) {
         return "shell";
     if (tool === "capability")
         return "capability";
+    if (tool === "batch")
+        return "batch";
     return "tool";
 }
 function activityTitle(tool) {
@@ -138,12 +168,24 @@ function activityTitle(tool) {
         exec_command: "Command",
         bash_result: "Bash result",
         capability: "Capability",
+        batch: "Batch",
     };
     return titles[tool] ?? tool;
 }
 function activityTarget(record, request, result, structured) {
     if (record.tool === "bash" || record.tool === "exec_command")
         return "Shell command";
+    if (record.tool === "batch") {
+        const tasks = arrayField(request, "tasks");
+        return `${tasks?.length ?? 0} tasks`;
+    }
+    const paths = arrayField(request, "paths");
+    if (paths && paths.length > 0) {
+        if (record.tool === "read" || record.tool === "edit")
+            return `${paths.length} files`;
+        if (record.tool === "delete")
+            return `${paths.length} paths`;
+    }
     if (record.tool === "bash_result") {
         const processId = numberField(result, "processId") ?? numberField(request, "processId");
         const exitCode = numberField(result, "exitCode");

package/dist/capabilities.js

@@ -39,6 +39,12 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
         description: "Read-only semantic code navigation backed by external Language servers.",
         whenToRead: "Read before using code.intelligence or configuring Language servers.",
     },
+    {
+        name: "batch-execution",
+        description: "One-call execution of multiple independent ForgeRelay core operations.",
+        whenToRead: "Read before using batch.execute for heterogeneous multi-operation work.",
+        enabled: (config) => config.toolMode !== "codex",
+    },
 ];
 function capabilityGuidesDir() {
     return fileURLToPath(new URL("../capabilities", import.meta.url));
@@ -82,6 +88,9 @@ export function buildCapabilityFingerprint(config, version, context = {}) {
         "capability-guides.read",
         "code.intelligence",
     ];
+    if (config.toolMode !== "codex") {
+        capabilities.push("batch.execute");
+    }
     if (config.subagents) {
         capabilities.push("subagent.profiles");
     }

package/dist/capability-registry.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "./lsp/code-intelligence-types.js";
+import { batchExecuteInputSchema, } from "./operations/batch/types.js";
 export class CapabilityError extends Error {
     code;
     constructor(code, message) {
@@ -25,6 +26,7 @@ export class CapabilityRegistry {
                 name: definition.name,
                 description: definition.description,
                 available,
+                batchPolicy: definition.batchPolicy,
                 ...(!available && unavailableReason ? { unavailableReason } : {}),
                 guide: {
                     name: definition.guideName,
@@ -65,6 +67,9 @@ export class CapabilityRegistry {
         if (!catalogEntry.available) {
             throw new CapabilityError("capability_unavailable", `Capability ${name} is unavailable${catalogEntry.unavailableReason ? `: ${catalogEntry.unavailableReason}` : "."}`);
         }
+        if (options.batch && definition.batchPolicy === "unsupported") {
+            throw new CapabilityError("capability_batch_unsupported", `Capability ${name} is not supported inside batch.execute.`);
+        }
         if (options.nativeFile !== undefined && !definition.nativeFileArgument) {
             throw new CapabilityError("invalid_arguments", `Capability ${name} does not accept a Host-native file value.`);
         }
@@ -87,6 +92,9 @@ export class CapabilityRegistry {
             throw new CapabilityError("execution_failed", `Capability ${name} failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    batchPolicy(name) {
+        return this.definitions.get(name)?.batchPolicy;
+    }
     requireDefinition(name) {
         const definition = this.definitions.get(name);
         if (!definition) {
@@ -105,6 +113,7 @@ export class CapabilityRegistry {
             name: definition.name,
             description: definition.description,
             available,
+            batchPolicy: definition.batchPolicy,
             ...(!available && unavailableReason ? { unavailableReason } : {}),
             guide: {
                 name: definition.guideName,
@@ -152,6 +161,7 @@ export function createCapabilityRegistry(dependencies) {
             description: "Validate the active ForgeRelay Hook configuration for this workspace.",
             guideName: "lifecycle-hooks",
             readGuideBeforeFirstUse: true,
+            batchPolicy: "parallel",
             inputSchema: hooksCheckInput,
             availability: () => ({ available: true }),
             run: async (_input, context) => ({
@@ -167,6 +177,7 @@ export function createCapabilityRegistry(dependencies) {
                     description: "Review accumulated workspace changes from the Git-backed review checkpoint.",
                     guideName: "artifacts-review",
                     readGuideBeforeFirstUse: true,
+                    batchPolicy: "serial",
                     inputSchema: z.object({}).strict(),
                     availability: () => ({
                         available: dependencies.reviewChanges?.available ?? false,
@@ -181,6 +192,7 @@ export function createCapabilityRegistry(dependencies) {
                     description: "Read semantic code information through an available Language server without changing the Workspace.",
                     guideName: "code-intelligence",
                     readGuideBeforeFirstUse: true,
+                    batchPolicy: "parallel",
                     inputSchema: codeIntelligenceInput,
                     availability: () => ({
                         available: dependencies.codeIntelligence?.available ?? false,
@@ -189,12 +201,28 @@ export function createCapabilityRegistry(dependencies) {
                     run: async (input, context, options) => dependencies.codeIntelligence.run(input, context, options),
                 }]
             : []),
+        ...(dependencies.batchExecute
+            ? [{
+                    name: "batch.execute",
+                    description: "Execute multiple independent ForgeRelay core operations in one Agent interaction.",
+                    guideName: "batch-execution",
+                    readGuideBeforeFirstUse: true,
+                    batchPolicy: "unsupported",
+                    inputSchema: batchExecuteInputSchema,
+                    availability: () => ({
+                        available: dependencies.batchExecute?.available ?? false,
+                        reason: dependencies.batchExecute?.unavailableReason,
+                    }),
+                    run: async (input, context, options) => dependencies.batchExecute.run(input, context, options),
+                }]
+            : []),
         ...(dependencies.downloadArtifact
             ? [{
                     name: "artifact.download",
                     description: "Save one Host-native file into a workspace-relative destination without overwriting.",
                     guideName: "artifacts-review",
                     readGuideBeforeFirstUse: true,
+                    batchPolicy: "unsupported",
                     inputSchema: z.object({
                         file: z.strictObject({
                             download_url: z.string(),

package/dist/db/migrations.js

@@ -49,6 +49,16 @@ const migrations = [
         name: "activity-host-turns",
         up: migrateActivityHostTurns,
     },
+    {
+        version: 11,
+        name: "activity-parent-child",
+        up: migrateActivityParentChild,
+    },
+    {
+        version: 12,
+        name: "bash-output-audit-columns",
+        up: migrateBashOutputAuditColumns,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -316,6 +326,19 @@ function migrateActivityHostTurns(sqlite) {
       on activity_host_turns(created_at desc);
   `);
 }
+function migrateActivityParentChild(sqlite) {
+    sqlite.exec(`
+    alter table activity_audit_events add column parent_activity_id text;
+
+    create index if not exists activity_audit_events_parent_idx
+      on activity_audit_events(parent_activity_id, created_at);
+  `);
+}
+function migrateBashOutputAuditColumns(sqlite) {
+    addColumnIfMissing(sqlite, "bash_output_streams", "error", "text");
+    addColumnIfMissing(sqlite, "bash_output_streams", "returned", "integer not null default 0");
+    addColumnIfMissing(sqlite, "bash_output_streams", "completion_claimed_at", "text");
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/file-mutations.js

@@ -1,6 +1,6 @@
-import { lstat, realpath, rename, rm, rmdir, unlink } from "node:fs/promises";
+import { lstat, readdir, realpath, rename, rm, rmdir, unlink } from "node:fs/promises";
 import { resolve } from "node:path";
-import { expandHomePath, resolveCanonicalAllowedPath } from "./roots.js";
+import { expandHomePath, isPathInsideRoot, resolveCanonicalAllowedPath } from "./roots.js";
 export async function renamePath(input, context) {
     const source = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
     await assertNotAllowedRootItself(source, context.allowedRoots, input.path);
@@ -10,6 +10,37 @@ export async function renamePath(input, context) {
     await rename(source, destination);
     return { path: input.path, newPath: input.newPath };
 }
+export async function preflightDeletePaths(inputs, context) {
+    const targets = await Promise.all(inputs.map(async (input) => {
+        const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
+        await assertNotAllowedRootItself(path, context.allowedRoots, input.path);
+        const entry = await lstat(path);
+        const recursive = input.recursive ?? false;
+        if (entry.isDirectory() && !recursive) {
+            const entries = await readdir(path);
+            if (entries.length > 0) {
+                throw new Error(`Directory is non-empty: ${input.path}. Use recursive=true to delete it.`);
+            }
+        }
+        return {
+            inputPath: input.path,
+            canonicalPath: await realpath(path),
+        };
+    }));
+    for (let index = 0; index < targets.length; index += 1) {
+        const current = targets[index];
+        for (let otherIndex = index + 1; otherIndex < targets.length; otherIndex += 1) {
+            const other = targets[otherIndex];
+            if (current.canonicalPath === other.canonicalPath) {
+                throw new Error(`Bulk delete targets overlap: ${current.inputPath} and ${other.inputPath} resolve to the same path.`);
+            }
+            if (isPathInsideRoot(other.canonicalPath, current.canonicalPath) ||
+                isPathInsideRoot(current.canonicalPath, other.canonicalPath)) {
+                throw new Error(`Bulk delete targets overlap as ancestor/descendant paths: ${current.inputPath} and ${other.inputPath}.`);
+            }
+        }
+    }
+}
 export async function deletePath(input, context) {
     const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.allowedRoots);
     await assertNotAllowedRootItself(path, context.allowedRoots, input.path);

package/dist/mcp/server-instructions.js

@@ -24,11 +24,11 @@ export function buildToolDescriptions(config) {
         ? ""
         : " Use shell commands for search and directory inspection instead of dedicated MCP search tools.";
     return {
-        read: `Read a file inside an open workspace or the OS temp directory. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        read: `Read one file or multiple files inside an open workspace or the OS temp directory. Use path for one target or paths for multiple targets; offset/limit apply to every target in a bulk read. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        edit: `Edit one file inside an open workspace or the OS temp directory by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        edit: `Edit one file or multiple files inside an open workspace or the OS temp directory by replacing exact text blocks. Use path for one target or paths for multiple targets; a bulk Edit applies the same edits to every file and preflights all targets before the first mutation. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        delete: `Delete one path or multiple paths inside an open workspace or the OS temp directory. Use path for one target or paths for multiple targets; a bulk Delete preflights all targets before deleting anything. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         shell: `Run or manage a shell process inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace containment does not make shell execution a sandbox. For action=run, yieldTimeMs is only the feedback wait (default 10000ms; 0 returns a processId immediately) and optional timeoutMs is the independent total execution limit. action=process polls/waits for incremental output, writes input, resizes a PTY, or interrupts by processId. Keep explicit waits below the Host request deadline; use 60000ms only when supported. Completed background results may be attached to a later result for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",