TSUKA is engineered to automate real-world software engineering and operational tasks across operating systems (Windows, Linux, and macOS). Because executing shell scripts, modifying source files, and running autonomous multi-agent pipelines carry host-level operational risks, the framework enforces a multi-tier Defense-in-Depth security architecture strictly centered around the User-in-the-Loop principle.

┌─────────────────────────────────────────────────────────────────────────┐
│                           1. USER-IN-THE-LOOP                           │
│     PermissionManager: FIFO Prompt Queue · CLI / TUI Interactive Modals │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                    2. WORKSPACE JAIL & PATH CONFINEMENT                 │
│        resolveSafePath() · Path Traversal Blocking (CWE-22)             │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                  3. CREDENTIAL & SENSITIVE DATA MASKING                 │
│         Automatic Redaction: API Keys, Passwords, Tokens, Secrets       │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                  4. ISOLATED PARALLEL WORKSPACE STAGING                 │
│      Ephemeral Branch Sandboxes · Conflict-Aware Merge Detection        │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                  5. RUNTIME VM SANDBOX & USER-SPACE TOOLS               │
│        node:vm Isolation · Blocklist Policies · custom_tools/ User Space│
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                  6. DEFENSIVE SAST ENGINE (audit_code)                  │
│       CWE-798 · CWE-78/95 · CWE-89 · CWE-79 · CWE-327/295 · CWE-532    │
└─────────────────────────────────────────────────────────────────────────┘

Every native and dynamic tool registered in ToolRegistry declares an explicit risk tier. The PermissionManager guarantees that no state-modifying or potentially dangerous action executes without authorization:

All filesystem operations (read_file, write_file, edit_file, delete_file, list_dir, grep_search, audit_code) are strictly confined to the active workspaceRoot via the secure resolver resolveSafePath():

• Path Traversal Protection (CWE-22): Attempts to escape the workspace boundary using relative directory traversal (..) or absolute host paths are intercepted and rejected before touching the filesystem.
• Host System Isolation: Agents are unable to read or tamper with host system files, user home directories, SSH keys, or global OS settings.

// src/tools/impl/utils.ts
export function resolveSafePath(workspaceRoot: string, targetPath: string): string {
  const resolved = path.resolve(workspaceRoot, targetPath);
  if (!resolved.startsWith(workspaceRoot)) {
    throw new Error(`Access denied: path '${targetPath}' is outside the workspace jail.`);
  }
  return resolved;
}

TSUKA automatically scrubs sensitive credentials from all communication pipelines (maskEnvVars):

• Environment Variable Redaction: Any loaded .env variables or system environment keys matching sensitive patterns (KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL, AUTH) are automatically masked.
• Omnichannel Protection: Scrubbing occurs before data reaches LLM prompts, persistent run logs (workflow_logs/), the CLI console stream, or the TUI screen buffers.

In concurrent multi-agent or parallel branch workflows (PARALLELO blocks in /goal):

• Multiple concurrent agents may request permissions simultaneously.
• The PermissionManager sequentially chains interactive prompts through an asynchronous FIFO queue (enqueuePrompt).
• Terminal Stream Protection: Prompts appear one at a time, eliminating stdin collisions and double-buffered TUI modal corruption.

During parallel branch execution in the Goal Orchestrator:

1. Isolated Staging: Each agent operates in an isolated temporary staging directory managed via AsyncLocalStorage.
2. Deterministic Merge: Upon completing the parallel block, file changes are merged into the real workspace with conflict detection (blocking silent concurrent overwrites).
3. Automatic Teardown: Temporary staging folders are cleanly pruned upon completion.

TSUKA allows agents to safely author new tools at runtime:

• node:vm Sandbox Execution: Generated tool code is evaluated in an isolated virtual machine context with restricted globals (fs and path only, no eval(), new Function(), process.exit, process.env, or unvetted modules).
• User-Space Isolation (custom_tools/): Self-authored tools and JSON schemas are stored in custom_tools/ and custom_tools_schemas/ (git-ignored), preventing accidental corruption of the framework's source repository.
• Core Protection: Dynamic tools cannot overwrite or shadow native core tools.
• Automatic Versioning & Backup: Updated custom tools are versioned and backed up in tools_backup/.

TSUKA includes a built-in static application security testing engine (audit_code) to scan codebase files for common security vulnerabilities:

• path: Specific file or directory to scan.
• severityThreshold: Severity filter (HIGH, MEDIUM, LOW).
• fileExtensions: Target file extensions (e.g. ['.ts', '.js', '.py', '.php', '.env']).
• maxIssues: Maximum number of reported issues.

• Typed Inter-Agent Contracts: Agent transitions and voting use structured protocol tools (report_status, route_next, cast_vote).
• Turn Interrupt (Esc / Ctrl+X): Users can instantly interrupt execution at any time; the abort signal (AbortSignal) immediately propagates across all active subagents and running tools.
• Subagent Safety Inheritance (spawn_agent): Subagents inherit the parent's workspace jail, token budgets, and permission handlers.