expose shell process group id to model, along with instructions for how to terminate or signal the group (#645)

2 files changed, 4 insertions, 1 deletions

diff --git a/packages/core/src/tools/shell.md b/packages/core/src/tools/shell.md
index 069a76db..17c39196 100644
--- a/packages/core/src/tools/shell.md
+++ b/packages/core/src/tools/shell.md
@@ -1,6 +1,7 @@
 This tool executes a given shell command as `bash -c <command>`.
 Command can start background processes using `&`.
-Command itself is executed as a subprocess.
+Command is executed as a subprocess that leads its own process group.
+Command process group can be terminated as `kill -- -PGID` or signaled as `kill -s SIGNAL -- -PGID`.
 
 The following information is returned:
 
@@ -12,3 +13,4 @@ Error: Error or `(none)` if no error was reported for the subprocess.
 Exit Code: Exit code or `(none)` if terminated by signal.
 Signal: Signal number or `(none)` if no signal was received.
 Background PIDs: List of background processes started or `(none)`.
+Process Group PGID: Process group started or `(none)`
diff --git a/packages/core/src/tools/shell.ts b/packages/core/src/tools/shell.ts
index 4efc3500..d0cad218 100644
--- a/packages/core/src/tools/shell.ts
+++ b/packages/core/src/tools/shell.ts
@@ -282,6 +282,7 @@ export class ShellTool extends BaseTool<ShellToolParams, ToolResult> {
         `Exit Code: ${code ?? '(none)'}`,
         `Signal: ${processSignal ?? '(none)'}`,
         `Background PIDs: ${backgroundPIDs.length ? backgroundPIDs.join(', ') : '(none)'}`,
+        `Process Group PGID: ${shell.pid ?? '(none)'}`,
       ].join('\n');
     }