Skip to main content
Glama

Capture Process Scenario

capture_process_scenario
Destructive

Run a chosen command under a PTY and return process capture Evidence with residual unknowns, including terminal size, timeout, and finalization controls.

Instructions

Run one caller-selected command under a PTY and return process capture Evidence with residual unknowns. The renderer admits at most 1,000,000 combined terminal cells, computed as columns × (rows + scrollback); every resize uses the selected scrollback and must fit the same budget. Supply a smaller terminal shape when that product is too large; dimensions are never clamped. A command name resolves through the inherited PATH; the working directory defaults to the caller's current directory; host environment variables are inherited with scenario overrides. Environment keys cannot contain '=' or NUL, and REA_PROCESS_RUN_ID is reserved for process ownership. Filesystem snapshots are opt-in through filesystem_observation_paths. A positive finalization_ms makes a timeout or idle deadline send SIGTERM to the captured root through its start identity, keep observing, and send SIGKILL once after the interval; exit.finalization records each attempt with its delivery result and the observed exit, and cancellation still ends the run at once. The target runs with the current user's permissions; this is not a security sandbox.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "events": [],
      "limits": {
        "files": 10000,
        "processes": 1000,
        "file_bytes": 10000000,
        "output_bytes": 1000000,
        "filesystem_depth": 16
      },
      "terminal": {
        "rows": 24,
        "columns": 80,
        "scrollback": 1000
      },
      "arguments": [],
      "settle_ms": 100,
      "executable": "/usr/bin/true",
      "timeout_ms": 30000,
      "environment": {},
      "normalization": {
        "pids": true,
        "paths": false,
        "ports": true,
        "patterns": [],
        "time_bucket_ms": 10
      },
      "finalization_ms": 1500,
      "idle_timeout_ms": 30000,
      "working_directory": "/tmp",
      "filesystem_observation_paths": []
    },
    "name": "capture_process_scenario"
  }
}

Input Schema

NameRequiredDescriptionDefault
eventsNo
limitsNoResource budgets that bound execution and retained output for this operation.
terminalNoThe visible terminal and scrollback together must use at most 1,000,000 xterm renderer cells: columns × (rows + scrollback). Resize events use the same scrollback and limit.
argumentsNo
settle_msNo
executableYesCommand name or executable path to run.
timeout_msNo
environmentNo
normalizationNo
finalization_msNoMilliseconds a target may keep running after SIGTERM when timeout_ms or idle_timeout_ms fires, before SIGKILL; 0 sends SIGKILL immediately. Both signals reach the captured root only while its launch-time start identity still matches; cancellation ends the run at once.
idle_timeout_msNo
working_directoryNo
filesystem_observation_pathsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive/openWorld/non-idempotent, and the description adds substantial context beyond them: runs as the current user, explicitly not a security sandbox, PATH resolution, env inheritance with overrides, the reserved REA_PROCESS_RUN_ID key, and the SIGTERM-then-SIGKILL finalization guarded by start identity. It does not discuss cancellation semantics beyond 'ends at once' or what happens to child processes outside the root.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose, which is good, but the remainder is a single dense wall of prose mixing terminal budgets, env rules, signal handling, and security caveats with no structure or grouping. Each fact is relevant, yet the density makes selective retrieval harder than it needs to be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive 13-parameter tool with no output schema, the description covers execution environment, limits, signal lifecycle, and safety posture thoroughly. The main gap is the return contract: 'process capture Evidence with residual unknowns' is not explained, and event scripting / normalization / limits semantics are left entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 13 parameters and low schema description coverage (31%), the description compensates well: it explains the terminal cell budget formula (columns x (rows + scrollback)) and no-clamping behavior, executable PATH resolution, working_directory default, environment key restrictions, opt-in filesystem_observation_paths, and finalization_ms timing. events, arguments, settle_ms, limits, and normalization remain undocumented in both prose and schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource: run a caller-selected command under a PTY and return process capture Evidence. That clearly separates it from the capture_browser_scenario / capture_electron_scenario / capture_native_ui_scenario family, but the description never names or contrasts any sibling directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied via constraints (supply a smaller terminal shape when the cell product is too large, snapshots are opt-in, set finalization_ms for a graceful kill window). There is no explicit 'use this when X, use compare_process_captures when Y' routing, and no stated prerequisites for choosing this over the other capture_* tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools