This document describes the security threat model and mitigations implemented in AgentLoop (Task 4.3).

AgentLoop executes LLM-generated tool calls. Because the model may produce malicious or erroneous inputs — whether due to prompt injection, adversarial instructions in retrieved documents, or simple hallucination — all LLM-generated tool arguments must be treated as untrusted.

The primary attack vectors are:

All file operations (file-read, file-write, file-edit, file-delete, file-list) and the working-directory (cwd) parameter of shell and code_run are resolved through resolveSafe (src/tools/file-utils.ts).

resolveSafe calls path.resolve() and then asserts that the result lies inside WORKSPACE_ROOT. Any path that resolves outside the root — including ../../etc/passwd, absolute paths, or symlink tricks — raises an error before any filesystem operation is attempted.

Configuration: WORKSPACE_ROOT (default: process.cwd()).

The shell tool uses execFile (not exec), which never spawns a system shell, so shell metacharacters in the command string are not interpreted by the OS. Despite this, the presence of metacharacters (;, &&, ||, |, `, $(, \n, \r) in the command string is treated as a strong signal of injection intent and the command is rejected before execution.

This is implemented in detectShellInjection (src/tools/sanitize.ts) and called by the shell tool's execute function.

Why reject even safe metacharacters? The tool's documented contract is that it runs a single executable with arguments split by whitespace. Any metacharacter indicates the caller is trying to use shell features that the tool intentionally does not support.

file-read checks stat.size before reading the file and raises if the size exceeds the limit. file-write computes the byte length of the decoded content buffer before writing.

This prevents the agent from reading enormous files into memory (denial of service) or writing unbounded output to disk.

The stdout and stderr of every shell command are passed through truncateOutput (src/tools/sanitize.ts), which slices the UTF-8 byte representation at MAX_SHELL_OUTPUT_BYTES and appends a notice. This bounds the size of the ToolMessage injected back into the LLM context.

All tool invocations in both the standard and streaming agent loops pass through a ConcurrencyLimiter semaphore (src/security.ts). When the number of active executions reaches MAX_CONCURRENT_TOOLS, additional invocations queue and wait for a slot to become free. Setting the value to 0 disables the limit entirely.

checkNetworkAccess(url, allowedDomains) (src/security.ts) validates that the hostname of a URL is permitted by the configured allowlist. A hostname matches if it is exactly in the list, or if it is a subdomain of a listed domain.

When NETWORK_ALLOWED_DOMAINS is empty (the default), all hosts are permitted.

This function must be called by any tool that makes outbound HTTP requests. Currently no bundled tools make direct network requests; the control is in place for future tools (e.g., web-fetch, web-search).

Configuration: NETWORK_ALLOWED_DOMAINS — comma-separated list of permitted hostnames (e.g., api.openai.com,docs.python.org).

ToolPermissionManager (src/security.ts) enforces three layers of access control before any tool is executed:

1. Blocklist — tools in TOOL_BLOCKLIST are always rejected.
2. Allowlist — when TOOL_ALLOWLIST is non-empty, only listed tools run.
3. Permission level — "safe" (auto-approved), "cautious" (auto-approved with audit log), "dangerous" (requires user confirmation unless AUTO_APPROVE_ALL=true).

Dedicated security tests live in src/__tests__/security-hardening.test.ts and cover:

• Path traversal attempts for file-read and file-write
• Shell injection metacharacter detection (detectShellInjection)
• Shell tool blocking injection attempts at execution time
• Shell cwd confinement to workspace root
• Shell output truncation (truncateOutput)
• File size limit enforcement for file-read and file-write
• Network domain allowlist enforcement (checkNetworkAccess)
• Concurrency limiter semantics (ConcurrencyLimiter)

Run with:

npx jest --testPathPatterns="security-hardening"