feat(gateway): tool path hardening + sandbox escape prevention (P8-016)

Introduces path-guard.ts with guardPath (symlink-aware) and guardPathUnsafe
(lexical-only) that throw SandboxEscapeError on any escape attempt. Replaces
weak containment checks in file-tools, git-tools, and shell-tools with strict
guards. Adds 12 unit tests covering traversal, absolute-path, and sibling-dir
escape vectors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/TASKS.md

@@ -85,7 +85,7 @@
 | P8-013 | not-started | Phase 8   | Gateway Phase 5 — MosaicPlugin lifecycle, ReloadService, hot reload, system:reload TUI             | —    | #166          |
 | P8-014 | not-started | Phase 8   | Gateway Phase 6 — SessionGCService (all tiers), /gc command, cron integration                      | —    | #167          |
 | P8-015 | not-started | Phase 8   | Gateway Phase 7 — WorkspaceService, ProjectBootstrapService, teams project ownership               | —    | #168          |
-| P8-016 | not-started | Phase 8   | Security — file/git/shell tool strict path hardening, sandbox escape prevention                    | —    | #169          |
+| P8-016 | done        | Phase 8   | Security — file/git/shell tool strict path hardening, sandbox escape prevention                    | —    | #169          |
 | P8-017 | not-started | Phase 8   | TUI Phase 8 — autocomplete sidebar, fuzzy match, arg hints, up-arrow history                       | —    | #170          |
 | P8-018 | done        | Phase 8   | Spin-off plan stubs — Gatekeeper, Task Queue Unification, Chroot Sandboxing                        | —    | #171          |
 | P8-019 | not-started | Phase 8   | Verify Platform Architecture — integration + E2E verification                                      | —    | #172          |

docs/scratchpads/p8-016-tool-hardening.md

@@ -0,0 +1,55 @@
+# P8-016: Security — Tool Path Hardening + Sandbox Escape Prevention
+
+## Status: in-progress
+
+## Branch: feat/p8-016-tool-hardening
+
+## Issue: #169
+
+## Scope
+
+Harden file, git, and shell tool factories so no path operation escapes `sandboxDir`.
+
+## Files to Create
+
+- `apps/gateway/src/agent/tools/path-guard.ts` (new)
+- `apps/gateway/src/agent/tools/path-guard.test.ts` (new)
+
+## Files to Modify
+
+- `apps/gateway/src/agent/tools/file-tools.ts`
+- `apps/gateway/src/agent/tools/git-tools.ts`
+- `apps/gateway/src/agent/tools/shell-tools.ts`
+
+## Analysis
+
+### file-tools.ts
+
+- Has existing `resolveSafe()` function but uses weak containment check (relative path)
+- Replace with `guardPath` (for reads/lists on existing paths) and `guardPathUnsafe` (for writes)
+- Error pattern: return `{ content: [{ type: 'text', text: 'Error: ...' }], details: undefined }`
+
+### git-tools.ts
+
+- Has `clampCwd()` that silently falls back to sandbox root on escape attempt
+- Replace with strict `guardPath` that throws SandboxEscapeError, caught and returned as error
+- Also need to guard the `path` parameter in `git_diff`
+
+### shell-tools.ts
+
+- Has `clampCwd()` same silent-fallback approach
+- Replace with strict `guardPath` that throws SandboxEscapeError
+
+## Key Design Decisions
+
+- `guardPath`: uses `realpathSync.native` to resolve symlinks, requires path to exist
+- `guardPathUnsafe`: lexical only (`path.resolve`), for paths that may not exist yet
+- Both throw `SandboxEscapeError` on escape attempt
+- Callers catch and return error result
+
+## Verification
+
+- pnpm typecheck
+- pnpm lint
+- pnpm format:check
+- pnpm test