@superjackfruitlabs/salaam 0.0.4 → 0.0.5

package/src/local-coding.ts

@@ -11,7 +11,11 @@ import {
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { mkdtempSync, realpathSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
+import { classifyCommand, type DangerVerdict } from './command-danger.js';
+import { gitIdentityEnv, publishesToRemote } from './git-helpers.js';
+import { boundShellCommand } from './shell-passthrough.js';
+import type { ClassifierReview } from './danger-classifier.js';
 import { join } from 'node:path';
 import type { Store } from './store.js';
 import type { ManagedWork } from './managed.js';
@@ -20,16 +24,49 @@ import {
   prepareLocalEdits,
   verifyLocalEdits,
   applyLocalEdits,
+  reviewLocalEdits,
   type LocalEdit,
 } from './local-edits.js';
 import {
   permissionPolicy,
+  autoApprovesEdits,
+  autoApprovesCommands,
   permissionDigest,
-  matchesEditScope,
   assertPermissionBinding,
 } from './autonomy.js';
+import {
+  commandArgv,
+  evaluateRules,
+  type ApprovalRules,
+  type RuleRequest,
+} from './approval-rules.js';
 import { assertUndoSettled } from './local-undo.js';
-import { processIdentity } from './supervisor.js';
+import type { HookRun } from './hooks.js';
+import { processIdentity, processStart } from './supervisor.js';
+
+const TASK_TAIL = 65536;
+const TASK_LIMIT = 4;
+const BACKGROUND_LIFETIME = 2 * 3600 * 1000;
+type TaskState = 'running' | 'exited' | 'stopped' | 'timed_out' | 'lost';
+interface TaskRow {
+  id: string;
+  session_id: string;
+  call_id: string;
+  command: string;
+  state: TaskState;
+  pid: number | null;
+  identity: string | null;
+  exit_code: number | null;
+  started_at: string;
+  ended_at: string | null;
+}
+interface BackgroundTask {
+  id: string;
+  session: string;
+  done: Promise<void>;
+  output: () => { output: string; bytes: number; truncated: boolean };
+  stop: (why: TaskState) => void;
+}
 import {
   applyEditsAsTools,
   killToolGroup,
@@ -69,6 +106,8 @@ export interface LocalSandbox {
   /** The host config's `command_network: "broker"`: a sandboxed command reaches the network only
    * through this stk local-commands socket (operator rulings 2026-10-30). */
   network?: { socket: string };
+  /** Operator-allowed read-only paths outside the workspace (Phase 1, 2026-10-31). */
+  readPaths?: string[];
 }
 /** The proxy a broker-network command uses: only the relay on loopback, nothing direct. */
 function proxyEnv(port: number): Record<string, string> {
@@ -84,8 +123,23 @@ function proxyEnv(port: number): Record<string, string> {
 }
 export class LocalCoding {
   private jobs = new Map<string, { stop: () => void; done: Promise<void> }>();
+  /** Background tasks this controller owns; they belong to the session, not to a turn. */
+  private live = new Map<string, BackgroundTask>();
+  /** Output of recently ended tasks, so the model can read why one stopped. */
+  private kept = new Map<string, { output: string; bytes: number; truncated: boolean }>();
+  /** Background commands are for a person's own desk session only (Phase 3c). */
+  public interactive: (session: string) => boolean = () => false;
   private closed = false;
   private unregister: () => void;
+  /** Desk-session approval rules (allow/ask/deny), set by the service; absent means every request asks. */
+  public rules?: ApprovalRules;
+  /** Operator ruling 2026-11-01 (option 1): one command may ask to run outside the OS sandbox.
+   * Off where the host forbids full access, since it is full access for that one command. */
+  public allowOutsideSandbox = true;
+  /** The optional small-model command reviewer (Phase 4c); absent means the rules alone decide. */
+  public classifier?: {
+    review(session: string, command: string, cwd: string): Promise<ClassifierReview | null>;
+  };
   constructor(
     readonly store: Store,
     readonly managed: ManagedWork,
@@ -105,6 +159,20 @@ export class LocalCoding {
           throw new ServiceError('local_busy', 'Command resources are still active');
       },
     });
+    store.db.exec(
+      'CREATE TABLE IF NOT EXISTS local_tasks(id TEXT PRIMARY KEY,session_id TEXT NOT NULL,call_id TEXT NOT NULL,command TEXT NOT NULL,state TEXT NOT NULL,pid INTEGER,identity TEXT,exit_code INTEGER,started_at TEXT NOT NULL,ended_at TEXT)',
+    );
+    // A background task never outlives its controller: kill what a restart left and say so.
+    for (const raw of store.db.prepare("SELECT * FROM local_tasks WHERE state='running'").all()) {
+      const t = raw as unknown as TaskRow;
+      if (t.pid && t.identity && processStart(t.pid) === t.identity)
+        try {
+          process.kill(-t.pid, 'SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      this.endTask(t, 'lost', null);
+    }
     // A lost controller must never retry a possibly executed edit or command.
     for (const raw of store.db.prepare("SELECT * FROM local_calls WHERE state='running'").all()) {
       const c = raw as unknown as LocalCall;
@@ -126,6 +194,26 @@ export class LocalCoding {
       });
     }
   }
+  /** The exact edits an edit request carries, or none for a command; files over 256 KiB are left out. */
+  edits(
+    session: string,
+    by: { operation: string } | { toolCall: string },
+  ): { root: string; edits: LocalEdit[] } | null {
+    const row = this.store.db
+      .prepare(
+        `SELECT root,args FROM local_calls WHERE session_id=? AND ${'operation' in by ? 'operation_id' : 'tool_call'}=? ORDER BY rowid DESC LIMIT 1`,
+      )
+      .get(session, 'operation' in by ? by.operation : by.toolCall) as
+      { root: string; args: string } | undefined;
+    if (!row) return null;
+    const args = object(JSON.parse(row.args));
+    if (args.action !== 'edit') return null;
+    const small = (text: string | null) => text === null || Buffer.byteLength(text) <= 256 * 1024;
+    return {
+      root: row.root,
+      edits: (args.edits as LocalEdit[]).filter((e) => small(e.before) && small(e.after)),
+    };
+  }
   get(id: string): LocalCall {
     const row = this.store.db.prepare('SELECT * FROM local_calls WHERE id=?').get(id);
     if (!row) throw new ServiceError('not_found', 'Local operation not found', 404);
@@ -174,12 +262,70 @@ export class LocalCoding {
         'Another operation or uncertain outcome owns this workspace',
       );
   }
+  /** prepare, after the optional reviewer has looked at a command the session would run unasked. */
+  async prepareReviewed(
+    session: string,
+    epoch: number,
+    attempt: string,
+    toolCall: string,
+    input: Record<string, unknown>,
+  ) {
+    let review: ClassifierReview | null = null;
+    if (this.classifier && input.action === 'command' && typeof input.command === 'string') {
+      const p = permissionPolicy(this.store, session);
+      // Only where the mode would run the command without asking; review mode asks anyway.
+      if (p.access || p.mode === 'auto') {
+        const root = this.store.session(session).cwd;
+        if (!classifyCommand(input.command, this.dangerContext(root)).dangerous)
+          review = await this.classifier.review(session, input.command, root);
+      }
+    }
+    return this.prepare(session, epoch, attempt, toolCall, input, review);
+  }
+  private dangerContext(root: string) {
+    return {
+      root,
+      home: homedir(),
+      tmp: [...new Set(['/tmp', '/private/tmp', tmpdir(), realpathSync(tmpdir())])],
+    };
+  }
+  /** Has this tool call already been prepared? */
+  hasCall(session: string, epoch: number, toolCall: string): boolean {
+    return !!this.store.db
+      .prepare('SELECT 1 FROM local_calls WHERE session_id=? AND epoch=? AND tool_call=?')
+      .get(session, epoch, toolCall);
+  }
+  /** A `!command` turn runs only what was typed, once (trial polish #12): enforced here, not by
+   * the model following its instruction, so it holds in auto, full access and YOLO alike. */
+  private assertShellBinding(session: string, attempt: string, input: Record<string, unknown>) {
+    const row = this.store.db
+      .prepare(
+        'SELECT s.text FROM attempts a JOIN submissions s ON s.id=a.submission_id WHERE a.id=? AND a.session_id=?',
+      )
+      .get(attempt, session) as { text: string } | undefined;
+    const bound = row ? boundShellCommand(row.text) : undefined;
+    if (bound === undefined) return;
+    if (input.action !== 'command' || input.command !== bound || input.background)
+      throw new ServiceError(
+        'shell_binding',
+        `This turn runs only the command you typed: ${bound}. Run exactly that, unchanged.`,
+      );
+    const ran = this.store.db
+      .prepare('SELECT 1 FROM local_calls WHERE session_id=? AND attempt_id=?')
+      .get(session, attempt);
+    if (ran)
+      throw new ServiceError(
+        'shell_binding',
+        'This turn already ran the command you typed. Report its output; do not run anything else.',
+      );
+  }
   prepare(
     session: string,
     epoch: number,
     attempt: string,
     toolCall: string,
     input: Record<string, unknown>,
+    review: ClassifierReview | null = null,
   ) {
     const prior = this.store.db
       .prepare(
@@ -191,6 +337,7 @@ export class LocalCoding {
         throw new ServiceError('request_conflict', 'Tool call already binds different arguments');
       return this.view(String(prior.id));
     }
+    this.assertShellBinding(session, attempt, input);
     const root = this.store.session(session).cwd;
     const c: LocalCall = {
       id: randomUUID(),
@@ -215,6 +362,10 @@ export class LocalCoding {
           action: 'command';
           command: string;
           timeout_ms: number;
+          background?: true;
+          listen?: true;
+          /** Why this one command asked to run without the OS sandbox. */
+          outside_sandbox?: string;
           sandbox: { kind: string; level: string; bwrap: string | null; network?: 'broker' };
         };
     if (kind === 'edit') args = { action: 'edit', edits: prepareLocalEdits(root, input.edits) };
@@ -222,42 +373,87 @@ export class LocalCoding {
       const timeout = input.timeout_ms ?? 30000;
       if (!Number.isInteger(timeout) || Number(timeout) < 100 || Number(timeout) > 120000)
         throw new ServiceError('invalid_field', 'Command timeout must be 100–120000 ms');
+      const background = input.background === true;
+      if (input.background !== undefined && typeof input.background !== 'boolean')
+        throw new ServiceError('invalid_field', 'background must be true or false');
+      if (background) this.assertBackground(session);
+      if (input.listen !== undefined && typeof input.listen !== 'boolean')
+        throw new ServiceError('invalid_field', 'listen must be true or false');
       if (
-        this.sandbox.kind === 'bwrap' &&
-        this.sandbox.level !== 'full-access' &&
-        !this.sandbox.bwrap
+        input.outside_sandbox !== undefined &&
+        (typeof input.outside_sandbox !== 'string' || !input.outside_sandbox.trim())
       )
+        throw new ServiceError(
+          'invalid_field',
+          'outside_sandbox must say why the command needs to run without the sandbox',
+        );
+      const session_sb = this.sandboxFor(session);
+      // Only a sandboxed session has anything to step out of; under full access it changes nothing.
+      const outside =
+        typeof input.outside_sandbox === 'string' && this.sandboxed(session_sb)
+          ? input.outside_sandbox.trim().slice(0, 300)
+          : undefined;
+      if (outside !== undefined && (!this.allowOutsideSandbox || this.tools.mode === 'tools-user'))
+        throw new ServiceError(
+          'outside_sandbox_denied',
+          'The operator does not allow commands outside the OS sandbox on this host. Ask the person to run it themselves.',
+        );
+      const sb: LocalSandbox =
+        outside !== undefined ? { ...session_sb, level: 'full-access' } : session_sb;
+      // Operator ruling 2026-11-01 (option C): a sandboxed command listens only when a person
+      // approves that exact command to. Linux's sandbox has its own network, so it cannot serve.
+      const listen = input.listen === true && this.sandboxed(sb);
+      if (listen && sb.kind === 'bwrap')
+        throw new ServiceError(
+          'listen_unreachable',
+          'On Linux the command sandbox has its own network namespace, so a server it starts cannot be reached from the host. Ask for full access for this command, or run the server yourself.',
+        );
+      if (sb.kind === 'bwrap' && sb.level !== 'full-access' && !sb.bwrap)
         throw new ServiceError(
           'sandbox_unavailable',
           'This host has no usable bubblewrap, so it cannot run a sandboxed command; an operator can choose full access explicitly',
         );
-      if (
-        this.sandbox.kind === 'none' &&
-        this.sandbox.level !== 'full-access' &&
-        !this.sandbox.allowUnsandboxed
-      )
+      if (sb.kind === 'none' && sb.level !== 'full-access' && !sb.allowUnsandboxed)
         throw new ServiceError('sandbox_unavailable', UNSANDBOXED_REFUSAL);
       args = {
         action: 'command',
         command: string(input.command, 'command', 8192),
-        timeout_ms: Number(timeout),
+        timeout_ms: background ? BACKGROUND_LIFETIME : Number(timeout),
+        ...(background ? { background: true as const } : {}),
+        ...(listen ? { listen: true as const } : {}),
+        ...(outside !== undefined ? { outside_sandbox: outside } : {}),
         // Bound into the approval and the operation digest: the sandbox is part of what is approved.
         sandbox: {
-          kind: this.sandbox.kind,
-          level: this.sandbox.level,
-          bwrap: this.sandbox.bwrap?.version ?? null,
-          ...(this.brokerNetwork() ? { network: 'broker' as const } : {}),
+          kind: sb.kind,
+          level: sb.level,
+          bwrap: sb.bwrap?.version ?? null,
+          ...(this.brokerNetwork(sb) ? { network: 'broker' as const } : {}),
         },
       };
     } else throw new ServiceError('invalid_field', 'Choose edit or command');
     c.args = JSON.stringify(args);
+    // Operator ruling 2026-10-31: full access asks only for commands this check calls dangerous.
+    const rulesDanger: DangerVerdict =
+      args.action === 'command'
+        ? classifyCommand(args.command, this.dangerContext(root))
+        : { dangerous: false };
+    // Phase 4c: the reviewer can only add a reason to ask, never remove one.
+    const escalated = !rulesDanger.dangerous && args.action === 'command' && !!review?.escalate;
+    const danger: DangerVerdict = escalated
+      ? {
+          dangerous: true,
+          category: 'classifier',
+          reason: `${review!.reason} (reviewed by ${review!.model})`,
+          segment: (args as { command: string }).command,
+        }
+      : rulesDanger;
+    // Pushing and opening a pull request ask in every mode but YOLO (operator ruling 2026-10-31).
+    const publishes = args.action === 'command' ? publishesToRemote(args.command) : null;
     this.store.transaction(() => {
       const reviewed =
         args.action === 'edit'
-          ? args.edits
-              .map((e) => `--- ${e.path}\n${e.before ?? '(new file)'}\n+++ ${e.path}\n${e.after}`)
-              .join('\n\n')
-          : `Runs as ${this.tools.mode === 'tools-user' ? `tools user ${this.tools.user} (uid ${this.tools.uid})` : 'your local user'}, ${this.sandboxText()}\nDirectory: ${root}\nTimeout: ${args.timeout_ms} ms\nCommand:\n${args.command}`;
+          ? reviewLocalEdits(args.edits)
+          : `Runs as ${this.tools.mode === 'tools-user' ? `tools user ${this.tools.user} (uid ${this.tools.uid})` : 'your local user'}, ${this.sandboxText(this.bound(args), !!args.outside_sandbox)}\nDirectory: ${root}${args.background ? `\nRuns in the background until stopped (at most ${BACKGROUND_LIFETIME / 3600000} h); the last ${TASK_TAIL / 1024} KiB of output is kept` : `\nTimeout: ${args.timeout_ms} ms`}\n${danger.dangerous ? `Dangerous (${danger.category}): ${danger.reason}\n` : ''}${publishes ? `Publishes: ${publishes}; this always asks, except in YOLO\n` : ''}${args.outside_sandbox ? `Outside the sandbox: ${args.outside_sandbox}. This one command runs without the OS sandbox; the session stays sandboxed. This always asks, except in YOLO or your own rule\n` : ''}${args.listen ? 'May listen: this command may accept network connections. macOS cannot limit listening to localhost, so a server bound to 0.0.0.0 is reachable from your network. This always asks, except in YOLO or your own rule\n' : ''}Command:\n${args.command}`;
       const permission = this.managed.prepareWorkspaceInTransaction(
         session,
         epoch,
@@ -290,14 +486,100 @@ export class LocalCoding {
         action: kind,
       });
     });
+    if (review)
+      this.store.transaction(() =>
+        this.store.event(session, 'permission.classifier', {
+          call_id: c.id,
+          operation_id: c.operation_id,
+          model: review.model,
+          verdict: review.verdict,
+          escalated,
+          ...(review.reason ? { reason: review.reason } : {}),
+        }),
+      );
     const policy = permissionPolicy(this.store, session);
-    if (
-      args.action === 'edit' &&
-      matchesEditScope(
-        policy,
-        args.edits.map((e) => e.path),
-      )
-    ) {
+    // Desk-session rules: a matching deny refuses, a matching allow approves and is recorded with the
+    // rule that decided it; anything else falls through to the scoped-edit policy and then asks.
+    if (this.rules && policy.mode !== 'inspect' && this.rules.applies(session)) {
+      const request: RuleRequest =
+        args.action === 'command'
+          ? { tool: 'command', argv: commandArgv(args.command) }
+          : { tool: 'edit', paths: args.edits.map((e) => e.path) };
+      // A repo's allow rules cannot approve a dangerous or publishing command: only the person's own
+      // rules can.
+      const usable = (all: ReturnType<ApprovalRules['list']>) =>
+        danger.dangerous ||
+        publishes ||
+        (args.action === 'command' && (args.listen || args.outside_sandbox))
+          ? all.filter((r) => !(r.source === 'repo' && r.effect === 'allow'))
+          : all;
+      const decided = evaluateRules(usable(this.rules.list(session)), request);
+      const approval = this.managed.forOperation(c.operation_id);
+      const rule = decided.rule && {
+        id: decided.rule.id,
+        source: decided.rule.source,
+        effect: decided.rule.effect,
+        tool: decided.rule.tool,
+        ...(decided.rule.command ? { command: decided.rule.command } : {}),
+        ...(decided.rule.paths ? { paths: decided.rule.paths } : {}),
+      };
+      if (decided.effect === 'deny' && rule) {
+        this.managed.decide(
+          approval.id,
+          'rule-deny:' + c.id,
+          approval.revision,
+          approval.operation_digest,
+          'deny',
+        );
+        this.store.transaction(() =>
+          this.store.event(session, 'permission.rule-denied', {
+            rule,
+            call_id: c.id,
+            operation_id: c.operation_id,
+          }),
+        );
+      } else if (decided.effect === 'allow' && rule) {
+        const rules = this.rules;
+        this.managed.decide(
+          approval.id,
+          'rule:' + c.id,
+          approval.revision,
+          approval.operation_digest,
+          'approve',
+          {
+            receipt: {
+              policy_digest: permissionDigest(policy),
+              policy_revision: policy.revision,
+              rule,
+              root,
+              call_id: c.id,
+            },
+            decidedBy: 'rule:' + rule.source,
+            authorize: () => {
+              this.guard(c);
+              const again = evaluateRules(usable(rules.list(session)), request);
+              if (again.effect !== 'allow' || again.rule?.id !== rule.id)
+                throw new ServiceError('permission_changed', 'Approval rules changed');
+            },
+          },
+        );
+      }
+    }
+    // The session's mode approves by itself only what it covers (Phase 2b): scoped or ordinary
+    // project edits, and, in auto, commands that stay inside the OS sandbox. Re-checked at decision.
+    const covered = (p: typeof policy) =>
+      args.action === 'edit'
+        ? autoApprovesEdits(
+            p,
+            args.edits.map((e) => e.path),
+          )
+        : autoApprovesCommands(
+            p,
+            this.sandboxed(this.bound(args)),
+            danger.dangerous,
+            publishes !== null || args.listen === true || !!args.outside_sandbox,
+          ) && !(escalated && p.access !== 'yolo');
+    if (this.managed.forOperation(c.operation_id).state === 'pending' && covered(policy)) {
       const approval = this.managed.forOperation(c.operation_id);
       this.managed.decide(
         approval.id,
@@ -315,19 +597,27 @@ export class LocalCoding {
           authorize: () => {
             this.guard(c);
             const fresh = permissionPolicy(this.store, session);
-            if (
-              permissionDigest(fresh) !== permissionDigest(policy) ||
-              args.action !== 'edit' ||
-              !matchesEditScope(
-                fresh,
-                args.edits.map((e) => e.path),
-              )
-            )
+            if (permissionDigest(fresh) !== permissionDigest(policy) || !covered(fresh))
               throw new ServiceError('permission_changed', 'Scoped edit policy changed');
-            verifyLocalEdits(root, args.edits);
+            if (args.action === 'edit') verifyLocalEdits(root, args.edits);
           },
         },
       );
+      // YOLO approves everything; each approval is recorded with what full access would have asked.
+      if (policy.access === 'yolo')
+        this.store.transaction(() =>
+          this.store.event(session, 'permission.yolo-approved', {
+            call_id: c.id,
+            operation_id: c.operation_id,
+            action: args.action,
+            ...(args.action === 'command' ? { command: args.command } : {}),
+            ...(danger.dangerous
+              ? { would_have_asked: { category: danger.category, reason: danger.reason } }
+              : publishes
+                ? { would_have_asked: { category: 'publish', reason: publishes } }
+                : {}),
+          }),
+        );
     }
     return this.view(c.id);
   }
@@ -396,30 +686,133 @@ export class LocalCoding {
           else this.managed.workspaceDefiniteFailureInTransaction(c.operation_id);
         });
       }
-    } else this.command(c, String(args.command), Number(args.timeout_ms));
+    } else if (args.background === true) this.background(c, String(args.command), this.bound(args));
+    else this.command(c, String(args.command), Number(args.timeout_ms), this.bound(args));
     return this.view(id);
   }
-  private sandboxText(): string {
-    const { kind, level } = this.sandbox;
+  /** The sandbox for a new command in this session: the host's, or full access if the person chose
+   * it for this session (Phase 2b). Bound into the command's approval and digest. */
+  private sandboxFor(session: string): LocalSandbox {
+    return permissionPolicy(this.store, session).access
+      ? { ...this.sandbox, level: 'full-access' }
+      : this.sandbox;
+  }
+  /** The sandbox a prepared command was approved under. */
+  private bound(args: { sandbox?: { level?: string } }): LocalSandbox {
+    return args.sandbox?.level === 'full-access'
+      ? { ...this.sandbox, level: 'full-access' }
+      : this.sandbox;
+  }
+  private sandboxed(sb: LocalSandbox): boolean {
+    return sb.kind !== 'none' && sb.level !== 'full-access';
+  }
+  /** Where this session's next command runs, in a word or two for the status and side panels. */
+  commandSandbox(session: string): string {
+    const access = permissionPolicy(this.store, session).access;
+    if (access) return access === 'yolo' ? 'YOLO' : 'full access';
+    if (this.sandbox.level === 'full-access') return 'no sandbox';
+    if (this.sandbox.kind === 'none')
+      return this.sandbox.allowUnsandboxed ? 'no sandbox' : 'refused';
+    return this.sandbox.kind === 'seatbelt' ? 'Seatbelt' : 'bubblewrap';
+  }
+  private sandboxText(sb: LocalSandbox = this.sandbox, outside = false): string {
+    const { kind, level } = sb;
+    if (outside)
+      return 'unsandboxed for this one command, at its own request: it can read and change any file your user can and reach the network.';
     if (level === 'full-access')
-      return 'unsandboxed: the operator chose full access. May access files and network beyond this workspace.';
+      return this.sandbox.level === 'full-access'
+        ? 'unsandboxed: the operator chose full access. May access files and network beyond this workspace.'
+        : 'unsandboxed: you turned on full access for this session. May access files and network beyond this workspace.';
     if (kind === 'none')
       return 'unsandboxed: this host has no usable command sandbox, so the command may access files and network beyond this workspace.';
     const name = kind === 'seatbelt' ? 'Seatbelt' : 'bubblewrap';
-    const net = this.brokerNetwork()
+    const net = this.brokerNetwork(sb)
       ? 'network: through the broker allowlist (hosts set by the stk policy), nothing direct.'
       : 'has no network.';
+    const reads = this.sandbox.readPaths?.length
+      ? ` It can also read ${this.sandbox.readPaths.length} operator-allowed path${this.sandbox.readPaths.length === 1 ? '' : 's'} outside the workspace.`
+      : '';
     return level === 'read-only'
-      ? `in a ${name} sandbox (read-only): it can read this workspace but write nothing, and ${net}`
-      : `in a ${name} sandbox (workspace-write): it can write only inside this workspace, and ${net}`;
+      ? `in a ${name} sandbox (read-only): it can read this workspace but write nothing, and ${net}${reads}`
+      : `in a ${name} sandbox (workspace-write): it can write only inside this workspace, and ${net}${reads}`;
   }
   /** Broker network applies only to a sandboxed command: unsandboxed ones are not confined anyway. */
-  private brokerNetwork(): { socket: string } | null {
-    return this.sandbox.network &&
-      this.sandbox.kind !== 'none' &&
-      this.sandbox.level !== 'full-access'
-      ? this.sandbox.network
-      : null;
+  private brokerNetwork(sb: LocalSandbox = this.sandbox): { socket: string } | null {
+    return sb.network && this.sandboxed(sb) ? sb.network : null;
+  }
+  /** Run a hook (Phase 4b) as one of this session's sandboxed commands would run: the same sandbox
+   * and level, no network, a minimal environment, `input` on stdin, bounded output and a timeout.
+   * Never as the tools user, whose process accounting is for approved operations only. */
+  runHook(session: string, command: string, input: string, timeoutMs: number): Promise<HookRun> {
+    const refused = (why: string): Promise<HookRun> =>
+      Promise.resolve({
+        code: null,
+        stdout: '',
+        stderr: '',
+        timedOut: false,
+        truncated: false,
+        refused: why,
+      });
+    if (this.tools.mode === 'tools-user')
+      return refused('Hooks do not run when commands run as a separate tools user');
+    const sb = this.sandboxFor(session);
+    if (sb.kind === 'bwrap' && sb.level !== 'full-access' && !sb.bwrap)
+      return refused('This host has no usable bubblewrap, so it cannot run a sandboxed hook');
+    if (sb.kind === 'none' && sb.level !== 'full-access' && !sb.allowUnsandboxed)
+      return refused(UNSANDBOXED_REFUSAL);
+    const root = this.store.session(session).cwd;
+    const tmp =
+      sb.kind === 'seatbelt' && sb.level !== 'full-access'
+        ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-hook-')))
+        : undefined;
+    const argv = this.commandArgv(root, command, tmp, null, sb);
+    const cap = 16 * 1024;
+    return new Promise<HookRun>((resolve) => {
+      let stdout = '',
+        stderr = '',
+        truncated = false,
+        timedOut = false;
+      const child = spawn(argv[0]!, argv.slice(1), {
+        cwd: root,
+        detached: true,
+        env: {
+          PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin',
+          HOME: process.env.HOME ?? root,
+          LANG: 'en_US.UTF-8',
+          TMPDIR: '/tmp',
+          SALAAM_PROJECT_DIR: root,
+          CLAUDE_PROJECT_DIR: root,
+        },
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const take = (current: string, chunk: Buffer) => {
+        const room = cap - Buffer.byteLength(current);
+        if (chunk.length > room) truncated = true;
+        return room > 0 ? current + chunk.subarray(0, room).toString('utf8') : current;
+      };
+      child.stdout.on('data', (c: Buffer) => (stdout = take(stdout, c)));
+      child.stderr.on('data', (c: Buffer) => (stderr = take(stderr, c)));
+      child.stdin.on('error', () => {});
+      child.stdin.end(input);
+      const timer = setTimeout(() => {
+        timedOut = true;
+        try {
+          process.kill(-child.pid!, 'SIGKILL');
+        } catch {
+          /* already gone */
+        }
+      }, timeoutMs);
+      const finish = (code: number | null) => {
+        clearTimeout(timer);
+        if (tmp) rmSync(tmp, { recursive: true, force: true });
+        resolve({ code: timedOut ? null : code, stdout, stderr, timedOut, truncated });
+      };
+      child.once('error', (error) => {
+        stderr = take(stderr, Buffer.from(error.message));
+        finish(null);
+      });
+      child.once('close', (code) => finish(code));
+    });
   }
   /** The process a command runs as. Under the tools user, the host-side shell reports its own
    * process group (the one a stop kills) before exec-ing bubblewrap, whose PID namespace would
@@ -429,23 +822,24 @@ export class LocalCoding {
     script: string,
     tmp?: string,
     relay?: BrokerRelay | null,
+    sb: LocalSandbox = this.sandbox,
+    listen = false,
   ): string[] {
-    const sandboxed = this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access';
+    const sandboxed = this.sandboxed(sb);
     const inner = (s: string) =>
       !sandboxed
         ? ['/bin/sh', '-c', s]
-        : this.sandbox.kind === 'seatbelt'
-          ? seatbeltArgv(
-              this.sandbox.level,
-              root,
-              tmp ?? '',
-              ['/bin/sh', '-c', s],
-              this.sandbox.seatbelt ?? null,
-              { network: false, ...(relay?.port ? { brokerPort: relay.port } : {}) },
-            )
-          : sandboxArgv(this.sandbox.level, root, ['/bin/sh', '-c', s], this.sandbox.bwrap, {
+        : sb.kind === 'seatbelt'
+          ? seatbeltArgv(sb.level, root, tmp ?? '', ['/bin/sh', '-c', s], sb.seatbelt ?? null, {
+              network: false,
+              ...(relay?.port ? { brokerPort: relay.port } : {}),
+              readPaths: sb.readPaths ?? [],
+              ...(listen ? { listen: true } : {}),
+            })
+          : sandboxArgv(sb.level, root, ['/bin/sh', '-c', s], sb.bwrap, {
               network: false,
               ...(relay?.dir ? { broker: { dir: relay.dir, node: process.execPath } } : {}),
+              readPaths: sb.readPaths ?? [],
             });
     if (this.tools.mode !== 'tools-user') return inner(script);
     const marker = 'umask 0002\nprintf \'salaam-tool-pgid:%s\\n\' "$$"\n';
@@ -461,11 +855,11 @@ export class LocalCoding {
         ])
       : toolArgv(this.tools, ['/usr/bin/setsid', '-w', '/bin/sh', '-c', marker + script]);
   }
-  private command(c: LocalCall, command: string, timeout: number): void {
-    const broker = this.brokerNetwork();
+  private command(c: LocalCall, command: string, timeout: number, sb: LocalSandbox): void {
+    const broker = this.brokerNetwork(sb);
     // The relay is Salaam's, outside the sandbox: it forwards to stk and counts what was reached.
     const relayStarting = broker
-      ? BrokerRelay.start(broker.socket, this.sandbox.kind === 'seatbelt' ? 'tcp' : 'unix')
+      ? BrokerRelay.start(broker.socket, sb.kind === 'seatbelt' ? 'tcp' : 'unix')
       : Promise.resolve(null);
     // A stop that arrives while the relay starts still cancels the command once it is spawned.
     let early = false;
@@ -474,7 +868,7 @@ export class LocalCoding {
     };
     // Seatbelt has no tmpfs: each command gets its own private tmp, removed when it ends.
     const tmp =
-      this.sandbox.kind === 'seatbelt' && this.sandbox.level !== 'full-access'
+      sb.kind === 'seatbelt' && sb.level !== 'full-access'
         ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-cmd-')))
         : undefined;
     const set = (s: () => void) => {
@@ -482,8 +876,8 @@ export class LocalCoding {
       if (early) s();
     };
     const done = relayStarting.then(
-      (relay) => this.runCommand(c, command, timeout, tmp, relay, set),
-      () => this.runCommand(c, command, timeout, tmp, null, set, !!broker),
+      (relay) => this.runCommand(c, command, timeout, tmp, relay, set, false, sb),
+      () => this.runCommand(c, command, timeout, tmp, null, set, !!broker, sb),
     );
     this.jobs.set(c.id, { stop: () => stop(), done });
     if (tmp) void done.finally(() => rmSync(tmp, { recursive: true, force: true }));
@@ -496,6 +890,7 @@ export class LocalCoding {
     relay: BrokerRelay | null,
     setStop: (stop: () => void) => void,
     relayFailed = false,
+    sb: LocalSandbox = this.sandbox,
   ): Promise<void> {
     let stop = () => {};
     return new Promise<void>((resolve) => {
@@ -508,7 +903,14 @@ export class LocalCoding {
       const tools = this.tools.mode === 'tools-user';
       const script = 'IFS= read -r salaam_start_gate || exit 125\nexec 0</dev/null\n' + command;
       // As the tools user, setsid makes the shell its own group leader so it can be killed by group.
-      const argv = this.commandArgv(c.root, script, tmp, relay);
+      const argv = this.commandArgv(
+        c.root,
+        script,
+        tmp,
+        relay,
+        sb,
+        JSON.parse(c.args).listen === true,
+      );
       let toolGroup: number | null = null,
         marker = tools ? '' : null,
         spawned = false;
@@ -525,6 +927,7 @@ export class LocalCoding {
           HOME: process.env.HOME ?? c.root,
           LANG: 'en_US.UTF-8',
           TMPDIR: '/tmp',
+          ...(this.sandboxed(sb) ? gitIdentityEnv(c.root) : {}),
           ...(relay ? proxyEnv(relay.port ?? COMMAND_NETWORK_PORT) : {}),
         },
         stdio: ['pipe', 'pipe', 'pipe'],
@@ -664,13 +1067,8 @@ export class LocalCoding {
           error: error ? 'Command could not start' : null,
           isolation:
             (tools ? 'tools-user-' : 'local-user-') +
-            (this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
-              ? this.sandbox.kind + '-' + this.sandbox.level
-              : 'no-os-sandbox'),
-          sandbox:
-            this.sandbox.kind !== 'none' && this.sandbox.level !== 'full-access'
-              ? this.sandbox.kind
-              : 'none',
+            (this.sandboxed(sb) ? sb.kind + '-' + sb.level : 'no-os-sandbox'),
+          sandbox: this.sandboxed(sb) ? sb.kind : 'none',
           tool_uid: this.tools.uid,
           ...(network ? { network } : {}),
         };
@@ -691,11 +1089,212 @@ export class LocalCoding {
       child.once('close', (code) => finish(code));
     });
   }
+  private assertBackground(session: string): void {
+    if (!this.interactive(session))
+      throw new ServiceError(
+        'background_denied',
+        'Background commands are only for an interactive local coding session',
+      );
+    if (this.tools.mode === 'tools-user')
+      throw new ServiceError(
+        'background_denied',
+        'Background commands do not yet run as a separate tools user',
+      );
+    if ([...this.live.values()].filter((t) => t.session === session).length >= TASK_LIMIT)
+      throw new ServiceError(
+        'background_limit',
+        `A session runs at most ${TASK_LIMIT} background commands; stop one first`,
+      );
+  }
+  /** Launch an approved background command. Its operation settles once the process is owned;
+   * the process then lives as a session task until it exits, is stopped, or the session ends. */
+  private background(c: LocalCall, command: string, sb: LocalSandbox): void {
+    const settle = (ok: boolean, result: Record<string, unknown>) =>
+      this.store.transaction(() => {
+        this.change(c, ok ? 'succeeded' : 'failed', result);
+        this.managed.localExecutionResultInTransaction(c.operation_id, ok, result);
+      });
+    try {
+      this.assertBackground(c.session_id);
+    } catch (error) {
+      settle(false, { error: (error as Error).message, background: true });
+      return;
+    }
+    const id = 'task_' + randomUUID().slice(0, 8);
+    const tmp =
+      sb.kind === 'seatbelt' && sb.level !== 'full-access'
+        ? realpathSync(mkdtempSync(join(tmpdir(), 'salaam-cmd-')))
+        : undefined;
+    // Network for a long-lived task needs a relay that lives as long; keep it simple and honest.
+    const script = 'IFS= read -r salaam_start_gate || exit 125\nexec 0</dev/null\n' + command;
+    const argv = this.commandArgv(
+      c.root,
+      script,
+      tmp,
+      null,
+      sb,
+      JSON.parse(c.args).listen === true,
+    );
+    const child = spawn(argv[0]!, argv.slice(1), {
+      cwd: c.root,
+      detached: true,
+      env: {
+        PATH: '/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin',
+        HOME: process.env.HOME ?? c.root,
+        LANG: 'en_US.UTF-8',
+        TMPDIR: '/tmp',
+        ...(this.sandboxed(sb) ? gitIdentityEnv(c.root) : {}),
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let tail = Buffer.alloc(0),
+      bytes = 0,
+      ended: TaskState | null = null,
+      resolve = () => {};
+    const done = new Promise<void>((r) => (resolve = r));
+    const kill = () => {
+      if (child.pid)
+        try {
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          /* already gone */
+        }
+    };
+    const task: BackgroundTask = {
+      id,
+      session: c.session_id,
+      done,
+      output: () => ({ output: tail.toString('utf8'), bytes, truncated: bytes > tail.length }),
+      stop: (why) => {
+        ended ??= why;
+        kill();
+      },
+    };
+    const collect = (chunk: Buffer) => {
+      bytes += chunk.length;
+      tail = Buffer.concat([tail, chunk]);
+      if (tail.length > TASK_TAIL) tail = tail.subarray(tail.length - TASK_TAIL);
+    };
+    child.stdout.on('data', collect);
+    child.stderr.on('data', collect);
+    child.stdin.on('error', () => {});
+    const lifetime = setTimeout(() => task.stop('timed_out'), BACKGROUND_LIFETIME);
+    // The session, not the turn, owns the task: it ends when local coding or its root goes away.
+    const watch = setInterval(() => {
+      try {
+        if (this.closed || !this.store.localCoding(c.session_id)) throw Error('closed');
+        if (this.store.session(c.session_id).cwd !== c.root) throw Error('moved');
+      } catch {
+        task.stop('stopped');
+      }
+    }, 1000);
+    const finish = (code: number | null) => {
+      clearTimeout(lifetime);
+      clearInterval(watch);
+      kill();
+      this.live.delete(id);
+      this.kept.set(id, task.output());
+      if (this.kept.size > 32) this.kept.delete(this.kept.keys().next().value!);
+      if (tmp) rmSync(tmp, { recursive: true, force: true });
+      const row = this.store.db.prepare('SELECT * FROM local_tasks WHERE id=?').get(id) as
+        TaskRow | undefined;
+      if (row) this.endTask(row, ended ?? 'exited', code);
+      else settle(false, { error: 'Command could not start', background: true });
+      resolve();
+    };
+    child.once('error', () => finish(null));
+    child.once('close', (code) => finish(code));
+    child.once('spawn', () => {
+      try {
+        // The start time, not processIdentity: the gated shell execs into the command.
+        const identity = processStart(child.pid!);
+        if (!identity) throw Error('No process identity');
+        this.store.transaction(() =>
+          this.store.db
+            .prepare(
+              "INSERT INTO local_tasks(id,session_id,call_id,command,state,pid,identity,started_at) VALUES (?,?,?,?,'running',?,?,?)",
+            )
+            .run(id, c.session_id, c.id, command, child.pid!, identity, new Date().toISOString()),
+        );
+        this.live.set(id, task);
+        settle(true, {
+          background: true,
+          task_id: id,
+          state: 'running',
+          isolation:
+            'local-user-' + (this.sandboxed(sb) ? sb.kind + '-' + sb.level : 'no-os-sandbox'),
+          sandbox: this.sandboxed(sb) ? sb.kind : 'none',
+          note: 'Read its output with salaam_tasks; it keeps running after this turn.',
+        });
+        child.stdin.end('start\n');
+      } catch {
+        ended = 'lost';
+        kill();
+      }
+    });
+  }
+  private endTask(t: TaskRow, state: TaskState, code: number | null): void {
+    this.store.transaction(() => {
+      this.store.db
+        .prepare(
+          "UPDATE local_tasks SET state=?,exit_code=?,ended_at=? WHERE id=? AND state='running'",
+        )
+        .run(state, code, new Date().toISOString(), t.id);
+      this.store.event(t.session_id, 'local.task_finished', {
+        task_id: t.id,
+        command: t.command.slice(0, 200),
+        state,
+        exit_code: code,
+      });
+    });
+  }
+  /** The session's background tasks, newest first. */
+  tasks(session: string) {
+    return (
+      this.store.db
+        .prepare(
+          'SELECT * FROM local_tasks WHERE session_id=? ORDER BY started_at DESC, rowid DESC',
+        )
+        .all(session) as unknown as TaskRow[]
+    ).map((t) => ({
+      id: t.id,
+      command: t.command,
+      state: t.state,
+      exit_code: t.exit_code,
+      pid: t.pid,
+      started_at: t.started_at,
+      ended_at: t.ended_at,
+      bytes: this.live.get(t.id)?.output().bytes ?? null,
+    }));
+  }
+  private task(session: string, id: string): TaskRow {
+    const row = this.store.db
+      .prepare('SELECT * FROM local_tasks WHERE id=? AND session_id=?')
+      .get(id, session) as TaskRow | undefined;
+    if (!row) throw new ServiceError('not_found', 'No such background task in this session', 404);
+    return row;
+  }
+  /** The kept tail of a task's output. Output of a task this controller no longer owns is gone. */
+  taskOutput(session: string, id: string) {
+    const row = this.task(session, id);
+    const live = this.live.get(id);
+    return {
+      task: { id: row.id, state: row.state, exit_code: row.exit_code },
+      ...(live?.output() ?? this.kept.get(id) ?? { output: '', bytes: 0, truncated: false }),
+    };
+  }
+  stopTask(session: string, id: string) {
+    this.task(session, id);
+    this.live.get(id)?.stop('stopped');
+    return { stopping: this.live.has(id) };
+  }
   async close(): Promise<void> {
     this.closed = true;
     const jobs = [...this.jobs.values()];
     for (const job of jobs) job.stop();
-    await Promise.all(jobs.map((j) => j.done));
+    const tasks = [...this.live.values()];
+    for (const t of tasks) t.stop('stopped');
+    await Promise.all([...jobs.map((j) => j.done), ...tasks.map((t) => t.done)]);
     this.unregister();
   }
 }