@ddtcorex/dsh-maestro-guard 0.1.0 → 0.2.1

package/src/host/index.ts

@@ -0,0 +1,184 @@
+import { execSync } from 'node:child_process'
+import type { Context } from '@deepseek-ai/cordis'
+import { ApprovalStore } from './approval-store.js'
+import { PermissionPolicy } from './permission-policy.js'
+import { PendingStore, ticketHash } from './pending.js'
+import { containsSecret, redact } from './secret-redactor.js'
+import { checkSandbox, extractCommandText, isBlockedCommand, isBlockedGitCommand, resolveCurrentBranch } from './sandbox.js'
+import { apply as applyFullScan } from './full-scan-tool.js'
+import { applyApproveTools } from './approve-tool.js'
+import type { GuardToolExecution, GuardPreToolDecision } from './augment.js'
+
+function getCurrentBranch(cwd?: string): string | undefined {
+  if (!cwd) return undefined
+  try {
+    return execSync('git branch --show-current', { cwd, timeout: 800, encoding: 'utf-8' }).trim() || undefined
+  } catch {
+    return undefined
+  }
+}
+
+function getSessionCwd(exec: unknown): string | undefined {
+  const e: any = exec as any
+  return (
+    e?.agent?.session?.header?.cwd ??
+    e?.session?.header?.cwd ??
+    e?.header?.cwd ??
+    e?.cwd ??
+    undefined
+  )
+}
+
+async function readGuardConfig(): Promise<Record<string, unknown>> {
+  try {
+    const mod: any = await import('@ddtcorex/dsh-maestro-config-lib')
+    if (typeof mod.load === 'function') {
+      try {
+        const doc = await mod.load()
+        if (doc?.domains?.guard && typeof doc.domains.guard === 'object' && !Array.isArray(doc.domains.guard)) {
+          return doc.domains.guard as Record<string, unknown>
+        }
+      } catch {}
+    }
+    if (typeof mod.get === 'function') {
+      try {
+        const g = await mod.get('guard')
+        if (g && typeof g === 'object' && !Array.isArray(g)) return g as Record<string, unknown>
+      } catch {}
+    }
+    if (typeof mod.readFlat === 'function') {
+      try {
+        const flat = await mod.readFlat()
+        if (flat && typeof flat === 'object' && (flat as any).guard && typeof (flat as any).guard === 'object') {
+          return (flat as any).guard as Record<string, unknown>
+        }
+      } catch {}
+    }
+  } catch {}
+  return {}
+}
+
+export function createGuardHandler(
+  store: ApprovalStore,
+  policy: PermissionPolicy,
+  pending: PendingStore,
+  readConfig: () => Promise<Record<string, unknown>> = readGuardConfig,
+) {
+  return async (exec: GuardToolExecution, next: () => Promise<GuardPreToolDecision>): Promise<GuardPreToolDecision> => {
+    const tool = (exec as GuardToolExecution).name ?? (exec as GuardToolExecution).tool ?? ''
+    const rawArgs = (exec as any)?.args ?? (exec as any)?.arguments
+
+    // Sandbox hard gate: credential paths, ~/.cloudflared, NPM_TOKEN, git-protection, publish, cwd (via checkSandbox)
+    const cwd = getSessionCwd(exec)
+    // Branch detection follows the repo the command actually targets (cd / git -C),
+    // not the session cwd — a session whose cwd repo sits on master must not block
+    // feature-branch pushes inside sub-repos (fix/guard-protection-precision).
+    const commandText = extractCommandText(rawArgs)
+    // Resolve the current branch lazily, only when the executed command could
+    // plausibly be a git/gh operation — otherwise every tool call (reads,
+    // writes, memory, unrelated bash) would spawn `git branch --show-current`
+    // for nothing.
+    const branchRelevant = commandText != null && /\b(git|gh)\b/i.test(commandText)
+    const currentBranch = branchRelevant ? resolveCurrentBranch(commandText, cwd, getCurrentBranch) : undefined
+    const asTextForSandbox = rawArgs != null ? JSON.stringify(rawArgs) : ''
+    const combinedForCheck = `${tool} ${asTextForSandbox}`
+    // Read guard config at runtime (injected lists) — fallback to defaults when empty
+    const guardCfg = await readConfig().catch(() => ({} as Record<string, unknown>))
+    const credentialPaths = Array.isArray((guardCfg as any).credentialPaths) ? (guardCfg as any).credentialPaths as string[] : undefined
+    const gitProtection = (guardCfg as any).gitProtection && typeof (guardCfg as any).gitProtection === 'object' ? (guardCfg as any).gitProtection as { enabled: boolean; branches: string[] } : undefined
+    const publishBlocked = typeof (guardCfg as any).publishBlocked === 'boolean' ? (guardCfg as any).publishBlocked as boolean : undefined
+    const cwdContainment = typeof (guardCfg as any).cwdContainment === 'boolean' ? (guardCfg as any).cwdContainment as boolean : undefined
+
+    const publishBlockedEffective = publishBlocked ?? true
+    const gitEnabled = gitProtection?.enabled ?? true
+    const branches = gitProtection?.branches ?? ['master', 'main']
+
+    const isPublish = publishBlockedEffective && commandText ? isBlockedCommand(commandText) : false
+    let approvedForPublish = false
+    if (isPublish) {
+      approvedForPublish =
+        (await store.isApproved('publish')) ||
+        (await store.isApproved('pnpm-publish')) ||
+        (await store.isApproved('pnpm publish')) ||
+        (await store.isApproved(tool))
+    }
+    const isGitProtected = gitEnabled && commandText ? isBlockedGitCommand(commandText, currentBranch, branches) : false
+    let approvedForGit = false
+    if (isGitProtected) {
+      approvedForGit =
+        (await store.isApproved('git-protection')) ||
+        (await store.isApproved('publish')) ||
+        (await store.isApproved(tool))
+    }
+    const sandboxRes = checkSandbox(tool, rawArgs, {
+      cwd,
+      currentBranch,
+      approved: isGitProtected ? approvedForGit : approvedForPublish,
+      credentialPaths,
+      gitProtection,
+      publishBlocked,
+      cwdContainment,
+    })
+    if (sandboxRes.blocked) {
+      const scope: 'git-protection' | 'publish' = sandboxRes.reason?.includes('publish') ? 'publish' : 'git-protection'
+      const sessionId = (exec as any)?.agent?.session?.id ?? undefined
+      // Hash over the executed command when available, not the full (tool + args)
+      // serialization — cosmetic arg fields (description, timeoutMs) must not
+      // mint a fresh ticket for a re-run of the same command (fix/guard-protection-precision).
+      const canonical = commandText ?? combinedForCheck
+      const cmdText = redact(canonical.slice(0, 300))
+      const hash = ticketHash(scope, cmdText)
+      const approved = await pending.findApprovedByHash(scope, hash, sessionId)
+      if (approved) {
+        await pending.consume(approved.id) // exactly one retry passes (consume is mutex-serialized)
+      }
+      if (!approved) {
+        try {
+          const req = await pending.record({
+            scope,
+            tool,
+            command: cmdText,
+            reason: sandboxRes.reason ?? 'blocked',
+            sessionId,
+            cwd,
+          })
+          throw new Error(`Guard: ${sandboxRes.reason} — request ${req.id}; present this exact operation in the conversation, then approve via the approve tool after the human consents`)
+        } catch (e) {
+          if (e instanceof Error && e.message.startsWith('Guard:')) throw e
+          throw new Error(`Guard: ${sandboxRes.reason}`)
+        }
+      }
+      // approved: fall through to the shared tail (policy check, secret redaction, next())
+    }
+
+    if (!policy.isAllowed(tool, rawArgs)) {
+      throw new Error(`Guard: tool ${tool} denied by policy`)
+    }
+    if (tool === 'danger-tool' && !(await store.isApproved(tool))) {
+      throw new Error(`Guard: tool ${tool} requires approval`)
+    }
+    if (rawArgs != null) {
+      const asText = JSON.stringify(rawArgs)
+      if (containsSecret(asText)) {
+        const redacted = JSON.parse(redact(asText))
+        if ('args' in exec) (exec as any).args = redacted
+        if ('arguments' in exec) (exec as any).arguments = redacted
+      }
+    }
+    return next()
+  }
+}
+
+export default {
+  inject: ['tools'] as const,
+  apply(ctx: Context) {
+    const store = new ApprovalStore()
+    const pending = new PendingStore()
+    const policy = new PermissionPolicy({ deny: ['danger-tool'] })
+    const handler = createGuardHandler(store, policy, pending)
+    ctx.effect(() => ctx.on('tools/pre-execute', handler as any))
+    // register on-demand full-scan tool (Task 4) alongside guard handler
+    applyFullScan(ctx, {})
+    applyApproveTools(ctx, { pending })
+  }
+}

package/src/host/pending.ts

@@ -0,0 +1,144 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { randomUUID, createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+function resolveHome(dshHome?: string) { return dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh') }
+export function pendingPath(dshHome?: string) { return join(resolveHome(dshHome), 'dsh-maestro-guard', 'pending.json') }
+
+export const MAX_PENDING = 20
+
+/**
+ * How long an approval (and a pending ticket) stays actionable. Approved grants
+ * must not linger indefinitely as standing one-shot passes for any later session,
+ * and superseded pending tickets should not clutter the store forever.
+ */
+export const APPROVAL_TTL_MS = 30 * 60 * 1000
+
+export interface PendingRequest {
+  id: string
+  scope: 'git-protection' | 'publish'
+  tool: string
+  hash: string
+  command: string
+  reason: string
+  sessionId?: string
+  cwd?: string
+  requestedAt: string
+  expiresAt?: string
+  status: 'pending' | 'approved' | 'consumed' | 'expired'
+}
+
+let _queue: Promise<unknown> = Promise.resolve()
+function enqueue<T>(fn: () => Promise<T>): Promise<T> {
+  const p = _queue.then(fn, fn) as Promise<T>
+  _queue = p.catch(() => {})
+  return p
+}
+
+export function ticketHash(scope: string, command: string): string {
+  return createHash('sha1').update(scope + '\u0000' + command).digest('hex').slice(0, 12)
+}
+
+function isExpired(req: PendingRequest, nowMs: number): boolean {
+  return !!req.expiresAt && nowMs > Date.parse(req.expiresAt)
+}
+
+export class PendingStore {
+  constructor(private dshHome?: string, private now: () => number = Date.now) {}
+  private async load(): Promise<{ requests: PendingRequest[] }> {
+    try { return JSON.parse(await readFile(pendingPath(this.dshHome), 'utf-8')) } catch { return { requests: [] } }
+  }
+  private async save(doc: { requests: PendingRequest[] }): Promise<void> {
+    const p = pendingPath(this.dshHome)
+    await mkdir(dirname(p), { recursive: true, mode: 0o700 })
+    await writeFile(p, JSON.stringify(doc, null, 2), { encoding: 'utf-8', mode: 0o600 })
+    await chmod(p, 0o600)
+  }
+  /** Mark expired pending/approved tickets as 'expired' (mutates, persists). */
+  private async prune(doc: { requests: PendingRequest[] }): Promise<void> {
+    const t = this.now()
+    let changed = false
+    for (const r of doc.requests) {
+      if ((r.status === 'pending' || r.status === 'approved') && isExpired(r, t)) {
+        r.status = 'expired'
+        changed = true
+      }
+    }
+    if (changed) await this.save(doc)
+  }
+  async record(opts: { scope: 'git-protection' | 'publish'; tool: string; command: string; reason: string; sessionId?: string; cwd?: string }): Promise<PendingRequest> {
+    return enqueue(async () => {
+      const doc = await this.load()
+      await this.prune(doc)
+      const hash = ticketHash(opts.scope, opts.command)
+      const existing = doc.requests.find(
+        (r) => r.scope === opts.scope && r.hash === hash && (r.status === 'pending' || r.status === 'approved'),
+      )
+      if (existing) return existing
+      const req: PendingRequest = {
+        id: `g-${randomUUID().slice(0, 8)}`,
+        scope: opts.scope,
+        tool: opts.tool,
+        hash,
+        command: opts.command,
+        reason: opts.reason,
+        sessionId: opts.sessionId,
+        cwd: opts.cwd,
+        requestedAt: new Date(this.now()).toISOString(),
+        expiresAt: new Date(this.now() + APPROVAL_TTL_MS).toISOString(),
+        status: 'pending',
+      }
+      doc.requests.push(req)
+      const pending = doc.requests.filter((r) => r.status === 'pending' || r.status === 'approved')
+      const resolved = doc.requests.filter((r) => r.status === 'consumed' || r.status === 'expired')
+      const drop = Math.max(0, resolved.length - (MAX_PENDING - pending.length))
+      await this.save({ requests: [...pending, ...resolved.slice(drop)] })
+      return req
+    })
+  }
+  async list(): Promise<PendingRequest[]> {
+    return enqueue(async () => {
+      const doc = await this.load()
+      await this.prune(doc)
+      return [...doc.requests].sort((a, b) => (a.requestedAt < b.requestedAt ? 1 : -1))
+    })
+  }
+  async approve(id: string): Promise<PendingRequest | undefined> {
+    return enqueue(async () => {
+      const doc = await this.load()
+      await this.prune(doc)
+      const req = doc.requests.find((r) => r.id === id)
+      if (!req || req.status !== 'pending') return undefined
+      req.status = 'approved'
+      req.expiresAt = new Date(this.now() + APPROVAL_TTL_MS).toISOString()
+      await this.save(doc)
+      return req
+    })
+  }
+  async consume(id: string): Promise<boolean> {
+    return enqueue(async () => {
+      const doc = await this.load()
+      const req = doc.requests.find((r) => r.id === id)
+      if (!req || req.status !== 'approved') return false
+      req.status = 'consumed'
+      await this.save(doc)
+      return true
+    })
+  }
+  async findApprovedByHash(scope: string, hash: string, sessionId?: string): Promise<PendingRequest | undefined> {
+    return enqueue(async () => {
+      const doc = await this.load()
+      await this.prune(doc)
+      const t = this.now()
+      return doc.requests.find(
+        (r) =>
+          r.scope === scope &&
+          r.hash === hash &&
+          r.status === 'approved' &&
+          !isExpired(r, t) &&
+          (r.sessionId ? r.sessionId === sessionId : true), // legacy tickets without a sessionId stay usable
+      )
+    })
+  }
+}

package/src/host/sandbox.ts

@@ -0,0 +1,322 @@
+import { homedir } from 'node:os'
+import { join, resolve, normalize } from 'node:path'
+
+function expandHome(p: string): string {
+  if (!p) return p
+  if (p === '~') return homedir()
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2))
+  if (p.startsWith('$HOME/')) return join(homedir(), p.slice(6))
+  if (p.startsWith('${HOME}/')) return join(homedir(), p.slice(8))
+  return p
+}
+
+function normalizePath(p: string): string {
+  try {
+    return normalize(expandHome(p))
+  } catch {
+    return expandHome(p)
+  }
+}
+
+/**
+ * True if path points to a blocked credential / secret location.
+ * Covers: ~/.dsh/.credentials.yaml (any expansion), ~/.cloudflared, NPM_TOKEN, .credentials.yaml substring
+ * credentialPaths: additional custom paths from config (guard.credentialPaths) — merged with always-blocked defaults.
+ * The 3 always-blocked substrings stay blocked even when credentialPaths is empty.
+ */
+export function isBlockedPath(input: string, credentialPaths?: string[]): boolean {
+  if (!input || typeof input !== 'string') return false
+  const trimmed = input.trim()
+  if (!trimmed) return false
+
+  // Direct substring checks (covers JSON-stringified args, env leakage, etc.) — always blocked
+  if (trimmed.includes('.credentials.yaml')) return true
+  if (trimmed.includes('.cloudflared')) return true
+  if (trimmed.includes('NPM_TOKEN')) return true
+  if (trimmed.includes('.dsh') && trimmed.includes('credentials')) return true
+
+  // Normalized expanded check for defaults
+  const norm = normalizePath(trimmed)
+  if (norm.includes('.credentials.yaml')) return true
+  if (norm.includes('.cloudflared')) return true
+  // Check absolute homedir variant
+  const absCred = join(homedir(), '.dsh', '.credentials.yaml')
+  if (norm === absCred || norm.startsWith(absCred)) return true
+  const absCf = join(homedir(), '.cloudflared')
+  if (norm === absCf || norm.startsWith(absCf + '/') || norm.includes('.cloudflared')) return true
+
+  // Injected credentialPaths from config (additional) — substring + normalized + prefix
+  if (credentialPaths && credentialPaths.length > 0) {
+    for (const p of credentialPaths) {
+      if (!p || typeof p !== 'string') continue
+      const t = p.trim()
+      if (!t) continue
+      if (trimmed.includes(t)) return true
+      const normP = normalizePath(t)
+      if (norm.includes(normP)) return true
+      if (norm === normP) return true
+      if (norm.startsWith(normP + '/')) return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * True if command string is a publish command (pnpm|npm publish)
+ */
+/**
+ * Resolve the working directory a command actually executes in, when it names
+ * one explicitly (cd <dir> / git -C <dir>). Falls back to the passed cwd when
+ * the command has no explicit target — preserving the historical session-cwd
+ * semantics for commands that run in place.
+ */
+export function getCommandWorkingDir(command: string | undefined, cwd: string | undefined): string | undefined {
+  if (!command || !cwd) return cwd ?? undefined
+  const hasCdVerb = /\bcd\b/.test(command) || /\bgit\s+-C\b/.test(command)
+  const cd = /\bcd\s+([^\s;&|"'`${}]+)(?:\s*(?:[;&|]|$))/.exec(command)
+  const c = /\bgit\s+-C\s+([^\s;&|"'`${}]+)/.exec(command)
+  const dir = cd?.[1] ?? c?.[1]
+  if (!dir) {
+    // A cd/-C verb is present but its target cannot be parsed (quoted, $VAR,
+    // wildcard, bare `cd`): do NOT assume the session cwd — that reintroduces
+    // the false positive when the session cwd repo sits on a protected branch.
+    // Unknown target means no protected-branch assumption (segment word checks
+    // still apply); commands with no cd verb keep the session-cwd semantics.
+    if (hasCdVerb) return undefined
+    return cwd
+  }
+  if (dir === '~') return homedir()
+  if (dir.startsWith('~/')) return join(homedir(), dir.slice(2))
+  return resolve(cwd, dir)
+}
+
+/**
+ * Choose the branch used for protected-branch detection: the branch of the repo
+ * the command targets (via `getCommandWorkingDir`), falling back to the session
+ * cwd when the command runs in place. If the command cd's into a directory that
+ * is not a git repo, no protected branch applies (the push would fail there
+ * anyway) — do NOT fall back to the session cwd, that reintroduces the
+ * false-positive where a feature-branch push inside a sub-repo is blocked
+ * because the session cwd repo happens to sit on master.
+ */
+export function resolveCurrentBranch(
+  command: string | undefined,
+  sessionCwd: string | undefined,
+  branchOf: (dir: string) => string | undefined,
+): string | undefined {
+  const dir = getCommandWorkingDir(command, sessionCwd)
+  if (!dir) return undefined
+  return branchOf(dir)
+}
+
+/**
+ * The executed command surface of a tool call. Shell-style tools carry their
+ * script in `args.command` (bash/exec/shell/govard_shell); bare string args are
+ * the command itself. Tools with no command field (read/write/memory/...) have
+ * no execution surface, so protected-op detection must not apply to their
+ * content — that was the source of the analysis-tool false positives.
+ */
+export function extractCommandText(args: unknown): string | undefined {
+  if (args == null) return undefined
+  if (typeof args === 'string') return args
+  if (typeof args === 'object' && typeof (args as Record<string, unknown>).command === 'string') {
+    return (args as Record<string, unknown>).command as string
+  }
+  return undefined
+}
+
+/** Collapse quoted spans — text inside quotes is data (echo/printf/script bodies), not argv. */
+function stripQuoted(cmd: string): string {
+  return cmd.replace(/"[^"]*"/g, ' ').replace(/'[^']*'/g, ' ')
+}
+
+export function isBlockedCommand(cmd: string): boolean {
+  if (!cmd || typeof cmd !== 'string') return false
+  // package-manager publish verbs as a whole-word sequence
+  return /\b(pnpm|npm)\s+publish\b/.test(stripQuoted(cmd))
+}
+
+/**
+ * True when the command executes a protected git operation. Detection is
+ * per-command-segment (split on && / ; / | / newline) so a `gh pr create
+ * --base master` mention after a feature push — or quoted text anywhere — does
+ * not turn a safe push into a blocked one. Hard rules (gh pr merge, gh release,
+ * protection deletion, protected branch words in the push segment, being
+ * checked out on a protected branch) keep their unconditional coverage.
+ */
+export function isBlockedGitCommand(cmd: string, currentBranch?: string, branches?: string[]): boolean {
+  if (!cmd || typeof cmd !== 'string') return false
+  const effectiveBranches = branches && branches.length > 0 ? branches : ['master', 'main']
+  const lowerBranches = effectiveBranches.map((b) => b.toLowerCase())
+  const escBranch = (b: string) => b.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  // Strip quoted spans on the FULL text BEFORE segmenting: a quoted block (an
+  // instruction prompt, a multiline -e body) legitimately spans &&/;|/newline
+  // separators, and segment-then-strip would fragment it, exposing the words.
+  const stripped = stripQuoted(cmd)
+  const segments = stripped.split(/\s*(?:&&|\|\||;|\||\r?\n)+\s*/)
+  for (const seg of segments) {
+    const lower = seg.toLowerCase()
+    // hard rules are unconditional per segment
+    if (/\bgh\s+pr\s+merge\b/.test(lower)) return true
+    if (/\bgh\s+release\s+(create|publish)\b/.test(lower)) return true
+    for (const b of lowerBranches) {
+      const re = new RegExp(`gh\\s+api\\b.*delete.*\\/branches\\/${escBranch(b)}\\/protection`)
+      if (re.test(lower)) return true
+    }
+    // git push: protected branch word in THIS segment, checked out on one, or
+    // pushing a release tag (version tags trigger the CI publish workflow and
+    // must follow the same human-approval rule as gh release create)
+    if (/\bgit\s+push\b/.test(lower)) {
+      for (const b of lowerBranches) {
+        if (new RegExp(`\\b${escBranch(b)}\\b`).test(lower)) return true
+      }
+      if (/refs\/tags\//.test(lower)) return true
+      // semver-like tag as a push refspec: standalone token (space/start
+      // preceded), so a branch name like feat/1.2.3 is not a false positive
+      if (/(?:^|\s)v?\d+\.\d+\.\d+(?:[-+][0-9a-z.]+)?\b/.test(lower)) return true
+      if (currentBranch) {
+        const curLower = currentBranch.toLowerCase()
+        if (lowerBranches.includes(curLower)) return true
+      }
+    }
+  }
+  // git tag push that includes protected branch (rare) — already covered by push regex
+  return false
+}
+
+export function isPublishBlocked(cmd: string, approved: boolean): boolean {
+  if (!isBlockedCommand(cmd)) return false
+  return !approved
+}
+
+/**
+ * True if target path is outside cwd (strict containment).
+ * Uses resolve for absolute comparison; expanded ~/ handled.
+ */
+export function isOutsideCwd(target: string, cwd: string): boolean {
+  if (!target || !cwd) return false
+  const expTarget = expandHome(target)
+  const expCwd = expandHome(cwd)
+  const resolvedTarget = resolve(expTarget)
+  const resolvedCwd = resolve(expCwd)
+  if (resolvedTarget === resolvedCwd) return false
+  // Ensure cwd prefix with separator to avoid /tmp/proj matching /tmp/proj2
+  return !resolvedTarget.startsWith(resolvedCwd + '/')
+}
+
+export interface SandboxCheckResult {
+  blocked: boolean
+  reason?: string
+}
+
+export interface CheckSandboxOpts {
+  cwd?: string
+  currentBranch?: string
+  approved?: boolean
+  credentialPaths?: string[]
+  gitProtection?: { enabled: boolean; branches: string[] }
+  publishBlocked?: boolean
+  cwdContainment?: boolean
+}
+
+/**
+ * Central sandbox check. Combines credential-path, git-protection, publish, and cwd containment.
+ * @param tool tool name (e.g. maestro_read_file, exec, bash)
+ * @param args tool arguments (object, string, or unknown)
+ * @param opts.cwd session cwd (exec.agent.session.header.cwd)
+ * @param opts.currentBranch git current branch (from getCurrentBranch)
+ * @param opts.approved whether publish/git is APPROVED (via ApprovalStore)
+ * @param opts.credentialPaths additional blocked credential paths from guard config
+ * @param opts.gitProtection git protection toggle + branches from guard config
+ * @param opts.publishBlocked whether publish is blocked (default true)
+ * @param opts.cwdContainment whether cwd containment is enforced (default true)
+ */
+export function checkSandbox(
+  tool: string,
+  args: unknown,
+  opts?: CheckSandboxOpts,
+): SandboxCheckResult {
+  const approved = !!opts?.approved
+  const cwd = opts?.cwd
+  const currentBranch = opts?.currentBranch
+  const credentialPaths = opts?.credentialPaths
+  const gitProtection = opts?.gitProtection
+  const publishBlocked = opts?.publishBlocked ?? true
+  const cwdContainment = opts?.cwdContainment ?? true
+
+  // Serialize args for generic substring checks
+  const asText = args != null ? (typeof args === 'string' ? args : JSON.stringify(args)) : ''
+  const combined = `${tool ?? ''} ${asText}`
+  // Protected-op detection (git/publish) runs on the executed command surface
+  // only — non-shell tools (write/read/memory/...) have no command and must not
+  // be flagged for text that merely mentions a protected phrase.
+  const execText = extractCommandText(args)
+
+  // 1) Block credential paths anywhere in tool+args (always, with injected list)
+  if (isBlockedPath(tool, credentialPaths) || isBlockedPath(asText, credentialPaths) || isBlockedPath(combined, credentialPaths)) {
+    return { blocked: true, reason: 'credential path blocked: ~/.dsh/.credentials.yaml or ~/.cloudflared or NPM_TOKEN' }
+  }
+
+  // 2) Block git push to protected branches without APPROVED (branch-aware, toggle-aware)
+  const gitEnabled = gitProtection?.enabled ?? true
+  const branches = gitProtection?.branches ?? ['master', 'main']
+  if (gitEnabled && execText && isBlockedGitCommand(execText, currentBranch, branches) && !approved) {
+    return { blocked: true, reason: 'git push to master/main blocked without APPROVED: ' + execText.slice(0, 300) }
+  }
+
+  // 3) Block publish without APPROVED (toggle-aware)
+  if (publishBlocked && execText && isBlockedCommand(execText) && !approved) {
+    return { blocked: true, reason: 'publish blocked without APPROVED: pnpm publish requires approval' }
+  }
+
+  // 4) Block maestro file tools outside cwd (toggle-aware)
+  const fileTools = new Set(['maestro_read_file', 'maestro_write_file', 'fs_read', 'fs_write', 'read_file', 'write_file'])
+  if (cwdContainment && cwd && fileTools.has(tool)) {
+    let pathVal: string | undefined
+    if (typeof args === 'object' && args !== null) {
+      const a = args as Record<string, unknown>
+      // common keys
+      pathVal = (a.path as string) ?? (a.file as string) ?? (a.file_path as string) ?? (a.filePath as string)
+      // array-like args: {0: 'path'}
+      if (!pathVal && typeof (a as any)[0] === 'string') pathVal = (a as any)[0] as string
+      // if args itself has nested command with path
+      if (!pathVal && typeof a.command === 'string') {
+        // command may contain path; fallback to blocked path check already done, but also cwd check if command contains path
+        // no explicit path to check
+      }
+    } else if (typeof args === 'string') {
+      pathVal = args
+    }
+    if (pathVal) {
+      if (isBlockedPath(pathVal, credentialPaths)) {
+        return { blocked: true, reason: `credential path blocked: ${pathVal}` }
+      }
+      if (isOutsideCwd(pathVal, cwd)) {
+        return { blocked: true, reason: `path outside cwd: ${pathVal} not in ${cwd}` }
+      }
+    }
+  }
+
+  // Also check generic exec/bash tool with cwd containment if it looks like a file path arg
+  // (optional: not strictly required for credential/publish but supports broader sandbox)
+  if (cwd && (tool === 'exec' || tool === 'bash' || tool === 'shell')) {
+    // already covered publish; for credential path we already blocked above via substring
+    // No additional cwd check for shell commands unless they are obvious file paths
+  }
+
+  return { blocked: false }
+}
+
+/**
+ * Simple guard per task 5 snippet: guard(p) => false if blocked, true if allowed.
+ * For publish, second arg approved indicates APPROVED.
+ */
+export function guard(p: string, approved?: boolean): boolean {
+  if (!p || typeof p !== 'string') return true
+  if (isBlockedPath(p)) return false
+  if (isBlockedCommand(p) && !approved) return false
+  return true
+}
+
+export const sandbox = { isBlockedPath, isBlockedCommand, isBlockedGitCommand, isPublishBlocked, isOutsideCwd, checkSandbox, guard }

package/src/sandbox.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export for Task 5 compatibility: `import { guard } from '../src/sandbox.js'`
+ * Real implementation lives in src/host/sandbox.ts (host-only, Cordis).
+ */
+export * from './host/sandbox.js';