docs: document process tool controls

src/agents/bash-tools.process-send-keys.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for process send-keys cursor-mode handling.
+ * Cursor-sensitive keys must wait until PTY startup output establishes mode.
+ */
 import { expect, test } from "vitest";
 import { createProcessSessionFixture } from "./bash-process-registry.test-helpers.js";
 import { handleProcessSendKeys, type WritableStdin } from "./bash-tools.process-send-keys.js";

src/agents/bash-tools.process-send-keys.ts

@@ -1,10 +1,14 @@
+/**
+ * Send-keys support for process-controlled PTY sessions.
+ * Encodes symbolic keys, hex bytes, and literal input before writing to a
+ * live process stdin.
+ */
 import type { ProcessSession } from "./bash-process-registry.js";
 import { deriveSessionName } from "./bash-tools.shared.js";
 import { encodeKeySequence, hasCursorModeSensitiveKeys } from "./pty-keys.js";
 import type { AgentToolResult } from "./runtime/index.js";
 
-// Process send-keys support for background PTY sessions. It encodes symbolic,
-// hex, and literal input before writing to a live session stdin.
+/** Writable stdin surface shared by child-process and PTY session records. */
 export type WritableStdin = {
   write: (data: string, cb?: (err?: Error | null) => void) => void;
   end: () => void;

src/agents/bash-tools.process.input-hints.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for process input-wait hints.
+ * Idle writable sessions should surface actionable metadata and user-facing hints.
+ */
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   addSession,

src/agents/bash-tools.process.poll-timeout.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for process poll timeout and retry hints.
+ * Poll waits, aborts, and diagnostic retry suggestions must stay bounded.
+ */
 import { afterEach, expect, test, vi } from "vitest";
 import { resetDiagnosticSessionStateForTest } from "../logging/diagnostic-session-state.js";
 import {

src/agents/bash-tools.process.supervisor.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Regression coverage for process-tool supervisor cancellation.
+ * Verifies managed session cancellation, process-tree fallback, and registry state.
+ */
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 
 const { supervisorMock } = vi.hoisted(() => ({

src/agents/bash-tools.process.ts

@@ -1,3 +1,8 @@
+/**
+ * Process-control tool factory.
+ * Lists, polls, logs, writes to, sends keys to, pastes into, kills, clears,
+ * and removes background exec sessions.
+ */
 import { formatDurationCompact } from "../infra/format-time/format-duration.ts";
 import { getDiagnosticSessionState } from "../logging/diagnostic-session-state.js";
 import { killProcessTree } from "../process/kill-tree.js";
@@ -30,6 +35,7 @@ import type { AgentToolResult } from "./runtime/index.js";
 import { PROCESS_TOOL_DISPLAY_SUMMARY } from "./tool-description-presets.js";
 import type { AgentToolWithMeta } from "./tools/common.js";
 
+/** Defaults injected by tests, agent scopes, and scoped process registries. */
 export type ProcessToolDefaults = {
   cleanupMs?: number;
   hasCronTool?: boolean;
@@ -171,6 +177,7 @@ async function sleepPollInterval(ms: number, signal?: AbortSignal): Promise<void
   });
 }
 
+/** Build the process-control tool with optional cleanup, scope, and input-idle defaults. */
 export function createProcessTool(
   defaults?: ProcessToolDefaults,
 ): AgentToolWithMeta<typeof processSchema, unknown> {
@@ -737,4 +744,5 @@ export function createProcessTool(
   };
 }
 
+/** Shared process-control tool instance used by the default Bash tool barrel. */
 export const processTool = createProcessTool();

src/agents/bash-tools.schemas.ts

@@ -1,12 +1,12 @@
-import { Type } from "typebox";
-import { optionalStringEnum } from "./schema/typebox.js";
-
 /**
  * TypeBox schemas for shell/process tools exposed to model providers.
  *
  * Keep these schemas provider-friendly: flat fields, string enums, and explicit
  * descriptions that match runtime validation.
  */
+import { Type } from "typebox";
+import { optionalStringEnum } from "./schema/typebox.js";
+
 const EXEC_TOOL_HOST_VALUES = ["auto", "sandbox", "gateway", "node"] as const;
 
 /** Parameters accepted by the exec tool. */

src/agents/bash-tools.test.ts

@@ -1,3 +1,7 @@
+/**
+ * Integration-style tests for the public Bash/process tool barrel.
+ * Exercises exec and process behavior through the shared exported tool factory.
+ */
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { drainFormattedSystemEvents } from "../auto-reply/reply/session-system-events.js";

src/agents/bash-tools.ts

@@ -1,5 +1,8 @@
-// Public Bash/process tool barrel. Implementation lives in focused exec,
-// process, schema, and description modules to keep host policy seams local.
+/**
+ * Public Bash/process tool barrel.
+ * Implementation lives in focused exec, process, schema, and description
+ * modules to keep host policy seams local.
+ */
 export type {
   BashSandboxConfig,
   ExecElevatedDefaults,