API Reference
ShellCreateTool (tool name: shell_create)
Creates a new persistent shell session. Returns a session ID for use with shell_command.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
cwd |
string | no | Working directory for this session. Must be within the workspace's accessible directories. Relative paths are resolved against the workspace. Defaults to the workspace's current path. The session is bound to the containing workspace root; permission checks for this session use that root. |
Returns: A session ID string.
ShellCommandTool (tool name: shell_command)
Executes a shell command in a persistent session. Supports shell compositions including pipes (|), logical operators (||, &&), and stream redirects.
When sessionId is omitted, empty, or whitespace-only, a new session is created in the current workspace once the command is allowed, and its id is reported in the result (see below). A non-empty id that is unknown or tombstoned keeps its descriptive error and never creates a session.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
command |
string | yes | The shell command to execute. |
sessionId |
string | no | The session ID from shell_create. When omitted or empty, a new session is created in the current workspace and its id is returned in the result. |
useCurrentWorkspace |
boolean | no | When true, the command runs in the current workspace and permissions are checked against it. If allowed, the session is permanently rebound to that workspace for all future permission checks and command cwds. Defaults to false (uses the session's bound workspace root and cwd). |
background |
boolean | no | When true, submit the command as a queued background job and return immediately with a job ID. Poll shell_job_status / shell_jobs for results. Defaults to false. |
timeout |
integer | no | Max idle time in ms (no stdout/stderr output) before the command is killed. Defaults to the configured foreground or background timeout; larger values are capped by the server config. |
Returns: Output of the command, or error message if denied/failed.
When a session was auto-created, the result begins with a delimited notice so the model can tell it apart from command output:
[shell_command] new session: <id>
[shell_command] --- begin output ---
<command output>
[shell_command] --- end output ---
With background=true the notice precedes the Background job <jobId> submitted ... line instead (both the session id and the job id are returned). Output for a provided, valid sessionId is unchanged.
Each job runs in its own working directory (the session's cwd, or the current workspace with useCurrentWorkspace: true); the executor re-anchors there before running, and a cd inside a command affects only that command.
ShellPermissionsTool (tool name: shell_permissions)
Returns the current workspace path and the effective permission rules / default action for the current workspace.
Parameters: none
Returns: A human-readable summary, e.g.:
Workspace: /path/to/ws-a
Workspace root: /path/to
Default: deny
Rules:
1. git * → allow
2. rm * → deny
ShellJobStatusTool (tool name: shell_job_status)
Returns the status and, once finished, the results (stdout, stderr, exit code) of a background job submitted with shell_command (background=true).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
jobId |
string | yes | The job ID returned by shell_command when background=true. |
Returns: A human-readable job report with status, working directory, timestamps, and (once completed) output, exit code, and timeout/session-alive flags.
ShellJobsTool (tool name: shell_jobs)
Lists the background jobs submitted to a session (queued, running, completed, failed), oldest first.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionId |
string | yes | The session ID from shell_create. |
Returns: One line per job in <status>\t<id>\t<cwd>\t<command> form, or No jobs for session <sessionId>.
SwitchWorkspaceTool (tool name: switch_workspace)
Changes the current workspace path to a new directory within the configured accessible directories (provided by the shared @johannes.latzel/llm-chat-workspace package). It only changes Workspace.currentPath; it does not touch any shell session or its working directory.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | yes | Target directory path within the configured accessible directories. |
Returns: Switched workspace to: <path>, or an error if the target is outside the accessible directories.
Sessions are decoupled from workspace switches. Existing sessions keep their original bound workspace root and cwd; use useCurrentWorkspace on shell_command to re-anchor them.
ShellCommandResult
Returned by BashShellExecutor.execute(). Tool results wrap the raw text in the common
PartialToolResult shape; the fields below describe the underlying command outcome.
| Field | Type | Description |
|---|---|---|
stdout |
string | Standard output of the command |
stderr |
string | Standard error of the command |
exitCode |
number | Exit code of the command (0 = success) |
timedOut |
boolean | True if the command was killed due to timeout |
sessionAlive |
boolean | False if the bash process was killed (session is dead) |
idleTimeoutMs |
number | Ms of inactivity (ctrlCTimeout) after which the command was timed out; present when timedOut is true |
Session death
Sessions do not survive death. When a session is timed out, idle-expired, exits, or is closed it is removed from the registry and recorded as a tombstone, so a stale session ID keeps returning a descriptive error instead of a bare "not found", for example:
Session <id> was killed because a command produced no output for too long (idle limit: 30000ms). Create a new session to continue.
Reasons: timeout (command produced no output for too long), expired (session idle
longer than sessionTimeout), process-exited, closed.
Permission System
Commands are evaluated against configured permission rules, configured globally and per workspace from a strict-JSON config file (see Configuration for the full schema). Each rule is { pattern, action, access?, type? }. The effective access (default read) and effective type (default command) come from the rule's own fields or the section's defaultAccess / defaultType. A write rule only applies in a workspace whose root grants write access.
Rule families
A single permissionRules list holds both families. A rule's effective type (type or defaultType) selects what it authorizes:
commandrules match command cores only (the command name and arguments, redirects stripped).redirectrules match redirect targets only (the literal path after a redirect operator).
A redirect target can never be authorized by a command rule and vice versa.
Redirect evaluation
Redirects default to deny: a target with no matching redirect rule is denied even when the core is allowed. output redirects (>, >>, >|, &>, &>>, <>) need a write-class allow redirect rule (gated by workspace write access); input redirects (<) need a read-class one. Targets match literally - no ~, env, or path resolution - and /dev/null needs an explicit rule. fd-dups and heredocs access no file and need none.
Effective workspace root and cwd for a session
shell_createbinds the session to the deepest workspace root containing the requestedcwd; all permission checks use that root.useCurrentWorkspace: truechecks against the current workspace and, on allow, permanently rebinds the session.switch_workspacenever changes a session's bound root or cwd; acdinside a command affects only that command.
Shell compositions
The permission system evaluates the full composed command: pipes (cmd1 | cmd2), &&, ||, and stream redirects (cmd > file).
ShellConfiguration
Configuration class for the shell executor. Timeouts and session limits read from environment variables; permission settings load from a config file pointed to by LLM_CHAT_SHELL_CONFIG.
import { ShellConfiguration } from '@johannes.latzel/llm-chat-shell';
const config = new ShellConfiguration();
Timeout properties
Env vars and their defaults are documented in Environment Variables.
| Property | Description |
|---|---|
ctrlCTimeout |
Foreground command idle timeout; the timer resets on each output |
sigtermTimeout |
SIGTERM-to-SIGKILL escalation grace period |
killTimeout |
Grace period after SIGKILL before giving up |
backgroundTimeout |
Fallback idle timeout for background jobs without an explicit timeout |
maxTimeout |
Cap applied to an LLM-supplied timeout; 0 disables the cap |
Session properties
| Property | Description |
|---|---|
maxSessions |
Concurrent session limit |
sessionTimeout |
Idle expiry for a session; sessions idle this long are closed by the background sweeper |
Permission properties
| Property | Description |
|---|---|
configFilePath |
Path to the strict-JSON permission config file; when set, defaultPermission, defaultType, defaultAccess, permissionRules, and workspacePermissions load from it |
defaultPermission |
Global default action for unmatched commands |
defaultType |
Global default rule type for rules without an explicit type; PermissionType.Command or PermissionType.Redirect |
defaultAccess |
Global default access for rules without an explicit access; PermissionAccess.Read or PermissionAccess.Write |
permissionRules |
Global rules for command cores and redirect targets; each is { pattern, action, access?, type? } |
workspacePermissions |
Per-workspace overrides as Map<resolvedRoot, WorkspacePermissions>; programmatic assignment takes precedence over the config file |
The config file schema and loading semantics are documented in Configuration; loadShellConfigFile(path) throws on an unreadable file, invalid JSON, or an invalid shape.
Methods
| Method | Description |
|---|---|
resolvePermissions(workspaceRoot: string) |
Returns the WorkspacePermissions for a root, falling back to the global defaultPermission / defaultType / defaultAccess / permissionRules when the root has no entry (or is ''). |
resolveIdleTimeout(background: boolean, requested?: number) |
Returns the effective idle timeout: a positive requested value wins (capped at maxTimeout when enabled); otherwise backgroundTimeout for background jobs, ctrlCTimeout for foreground commands. |
WorkspacePermissions
interface WorkspacePermissions {
defaultPermission: PermissionAction;
defaultType: PermissionType;
defaultAccess: PermissionAccess;
permissionRules: PermissionRule[];
}
PermissionType
A rule's effective type selects which surface it authorizes: command rules match
command cores, redirect rules match redirect targets. Rules without an explicit
type use the section's defaultType.
Package classes
ShellPackage
Groups the shell_create, shell_command, shell_permissions, shell_job_status, shell_jobs, and switch_workspace tools with a per-workspace permission system.
import { ShellPackage } from '@johannes.latzel/llm-chat-shell';
const pkg = new ShellPackage();
service.tools().add(pkg);
- Tools: shell_create, shell_command, shell_permissions, shell_job_status, shell_jobs, switch_workspace (6 tools)
- Constructor:
(config?, sessionManager?, workspace?): when asessionManageris provided its own workspace is used; otherwiseworkspace(or an internally builtWorkspace(new DirectoryConfiguration())) is shared by the tools. dispose(): closes all sessions and stops the idle-expiry sweeper (delegates to the session manager)