@superjackfruitlabs/salaam 0.0.4 → 0.0.5

package/src/session-pick.ts

@@ -0,0 +1,102 @@
+import { typedText } from './shell-passthrough.js';
+import { statSync } from 'node:fs';
+import { OFFLINE_ROUTE } from './provider-config.js';
+
+/** How `salaam code` opens a folder: continue its latest session (the default), start a new
+ * coding session, or pick one from the list. */
+export type CodeStart = 'continue' | 'new' | 'resume';
+
+export function parseCodeStart(flags: string[]): CodeStart {
+  const chosen = (['continue', 'new', 'resume'] as const).filter((f) => flags.includes('--' + f));
+  if (chosen.length > 1) throw new Error('Choose one of --continue, --new or --resume.');
+  return chosen[0] ?? 'continue';
+}
+
+const folder = (path: string) => (path.length > 1 ? path.replace(/\/+$/, '') : path);
+
+/** The most recently created session in this folder; sessions come oldest first. */
+export function latestSessionFor(
+  sessions: readonly { id: string; cwd: string }[],
+  cwd: string,
+): string | undefined {
+  const want = folder(cwd);
+  return [...sessions].reverse().find((s) => folder(s.cwd) === want)?.id;
+}
+
+/** Whether a new `salaam code` session should use Anthropic: only when nothing was chosen, the
+ * running service defaults to offline (as a TUI-started one does) and a key is stored. */
+export function deskUsesAnthropic(
+  chosen: boolean,
+  serviceProvider: string | undefined,
+  hasAnthropicKey: boolean,
+): boolean {
+  return (
+    !chosen &&
+    (serviceProvider ?? OFFLINE_ROUTE.provider) === OFFLINE_ROUTE.provider &&
+    hasAnthropicKey
+  );
+}
+
+/** `salaam -c` and `salaam --continue` are short for `salaam code --continue`. */
+export function continueArgs(args: readonly string[]): string[] | undefined {
+  if (args[0] !== '-c' && args[0] !== '--continue') return;
+  return ['code', '--continue', ...args.slice(1)];
+}
+
+interface PickerSession {
+  id: string;
+  cwd: string;
+  last_active_at?: string;
+}
+const activeAt = (s: { last_active_at?: string }) =>
+  s.last_active_at ? Date.parse(s.last_active_at) : -Infinity;
+
+/** This folder's sessions first, then every other one; newest first within each. */
+export function pickerOrder<T extends PickerSession>(sessions: readonly T[], cwd: string): T[] {
+  const want = folder(cwd);
+  const newest = (a: T, b: T) => activeAt(b) - activeAt(a);
+  const here = sessions.filter((s) => folder(s.cwd) === want).sort(newest);
+  return [...here, ...sessions.filter((s) => folder(s.cwd) !== want).sort(newest)];
+}
+
+export function relativeTime(at: string | undefined, now = Date.now()): string {
+  if (!at) return '';
+  const s = Math.max(0, (now - Date.parse(at)) / 1000);
+  if (s < 60) return 'just now';
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)} h ago`;
+  if (s < 2 * 86400) return 'yesterday';
+  return `${Math.floor(s / 86400)} days ago`;
+}
+
+/** One picker row: what you last asked (one short line), when, and where. */
+export function sessionDescription(
+  s: { cwd: string; state: string; last_prompt?: string; last_active_at?: string },
+  now = Date.now(),
+): string {
+  const prompt = s.last_prompt?.replace(/\s+/g, ' ').trim();
+  const quoted = prompt ? `“${prompt.length > 60 ? prompt.slice(0, 59) + '…' : prompt}”` : '';
+  return [quoted || s.state, relativeTime(s.last_active_at, now), s.cwd]
+    .filter(Boolean)
+    .join(' · ');
+}
+
+/** What the picker shows for a desk session: its newest prompt (at most 200 characters) and when
+ * its transcript last changed. Board and station sessions get nothing extra. */
+export function pickerSummary(
+  session: { id: string; capabilities: string[]; pi_session_file: string | null },
+  store: { lastPrompt(id: string): string | null },
+): { last_prompt?: string; last_active_at?: string } {
+  if (!session.capabilities.includes('local-coding-reviewed')) return {};
+  const prompt = store.lastPrompt(session.id);
+  let at: string | undefined;
+  try {
+    if (session.pi_session_file) at = statSync(session.pi_session_file).mtime.toISOString();
+  } catch {
+    /* no transcript yet */
+  }
+  return {
+    ...(prompt ? { last_prompt: typedText(prompt).slice(0, 200) } : {}),
+    ...(at ? { last_active_at: at } : {}),
+  };
+}

package/src/shell-passthrough.ts

@@ -0,0 +1,38 @@
+/**
+ * `!command` in a desk session (trial polish #12, 2026-10-31). The terminal never runs the command
+ * itself: it asks the model to run exactly that text through salaam_local. The service reads the
+ * same fixed prompt back from the turn's submission and binds the turn to the typed command, so a
+ * model that runs anything else is refused, whatever the session's mode.
+ */
+const LEAD = 'I want to run this shell command myself. Run exactly this command with salaam_local';
+
+export function shellPassthrough(text: string): string | undefined {
+  const t = text.trim();
+  if (!t.startsWith('!') || t.startsWith('!!')) return undefined;
+  const command = t.slice(1).trim();
+  if (command === '' || command.includes('\n') || command.includes('```')) return undefined;
+  return [
+    LEAD,
+    '(action "command"), unchanged: no edits, no extra flags, no other commands. Then show me its',
+    'output and exit status, and do nothing else unless I ask.',
+    '',
+    '```sh',
+    command,
+    '```',
+  ].join('\n');
+}
+
+/** The command a turn's prompt binds it to, when the prompt is exactly a `!command` request. */
+export function boundShellCommand(prompt: string): string | undefined {
+  if (!prompt.startsWith(LEAD + '\n')) return undefined;
+  const lines = prompt.split('\n');
+  if (lines.length !== 7 || lines[4] !== '```sh' || lines[6] !== '```') return undefined;
+  const command = lines[5]!;
+  return shellPassthrough('!' + command) === prompt ? command : undefined;
+}
+
+/** What the person typed, for display: `! COMMAND` for a `!command` prompt, else the text. */
+export function typedText(prompt: string): string {
+  const command = boundShellCommand(prompt);
+  return command === undefined ? prompt : '! ' + command;
+}

package/src/store.ts

@@ -572,8 +572,11 @@ export class Store {
     expected: number,
     controller: Controller,
     clone: (source: Session, target: string) => string,
+    /** A rewind forks from an earlier conversation leaf. */
+    at?: { leaf: string | null },
   ): Session {
-    return this.request('local-operator', request, { kind: 'fork', id, expected }, () => {
+    const input = { kind: 'fork', id, expected, ...(at ? { leaf: at.leaf } : {}) };
+    return this.request('local-operator', request, input, () => {
       this.authorizeControl(id, controller);
       const source = this.session(id);
       if (source.revision !== expected)
@@ -598,7 +601,7 @@ export class Store {
         .prepare(
           'INSERT INTO sessions(id,cwd,pi_session_id,pi_session_file,pi_cursor,pi_leaf) VALUES(?,?,?,?,?,?)',
         )
-        .run(target, source.cwd, target, file, source.pi_cursor, source.pi_leaf);
+        .run(target, source.cwd, target, file, source.pi_cursor, at ? at.leaf : source.pi_leaf);
       this.event(
         target,
         'session.created',
@@ -623,7 +626,13 @@ export class Store {
       this.event(
         target,
         'session.forked',
-        { parent: id, parent_revision: expected, leaf: source.pi_leaf, cursor: source.pi_cursor },
+        {
+          parent: id,
+          parent_revision: expected,
+          leaf: at ? at.leaf : source.pi_leaf,
+          cursor: source.pi_cursor,
+          ...(at ? { rewound: true } : {}),
+        },
         request,
       );
       return this.session(target);
@@ -655,6 +664,13 @@ export class Store {
   lastActivityAny(): number {
     return Math.max(this.openedAt, ...this.activity.values());
   }
+  /** The newest prompt submitted to a session, for the session picker. */
+  lastPrompt(id: string): string | null {
+    const row = this.db
+      .prepare('SELECT text FROM submissions WHERE session_id=? ORDER BY rowid DESC LIMIT 1')
+      .get(id) as { text: string } | undefined;
+    return row?.text ?? null;
+  }
   sessions(): Session[] {
     return (
       this.db.prepare('SELECT id FROM sessions ORDER BY rowid').all() as { id: string }[]
@@ -720,6 +736,27 @@ export class Store {
       }
     });
   }
+  /**
+   * The one sanctioned route change: an operator switching model or thinking level in an
+   * interactive session between turns. Recorded as provider.route_changed; the worker restarts on
+   * the same Pi transcript with the new route.
+   */
+  switchRoute(id: string, route: ProviderRoute): { from: ProviderRoute; to: ProviderRoute } {
+    return this.transaction(() => {
+      const from = this.providerRoute(id);
+      if (!from || !this.localWorkspace(id))
+        throw new ServiceError(
+          'route_switch_unavailable',
+          'Only interactive sessions can switch model mid-session',
+          409,
+        );
+      this.db
+        .prepare('UPDATE session_routes SET route=? WHERE session_id=?')
+        .run(canonical(route), id);
+      this.event(id, 'provider.route_changed', { from, to: route });
+      return { from, to: route };
+    });
+  }
   providerRoute(id: string): ProviderRoute | null {
     const row = this.db.prepare('SELECT route FROM session_routes WHERE session_id=?').get(id) as
       { route: string } | undefined;
@@ -1167,6 +1204,9 @@ export class Store {
     );
     let remaining = 256 * 1024;
     const messages: SessionSnapshot['messages'] = [];
+    // Walking back from the newest entry: tool calls belong just before the message that follows
+    // them, so a turn's calls are shown in place rather than gathered at the end.
+    let trailing: string[] = [];
     while (
       cursor &&
       !seen.has(cursor) &&
@@ -1181,6 +1221,14 @@ export class Store {
       cursor = entry.parentId ?? null;
       const message = entry.message;
       if (!message || !['user', 'assistant'].includes(message.role)) continue;
+      if (Array.isArray(message.content)) {
+        const calls = message.content
+          .filter((part: { type: string; id?: unknown }) => part.type === 'toolCall')
+          .map((part: { id: unknown }) => String(part.id));
+        const later = messages.at(-1);
+        if (calls.length && later) later.tool_calls = [...calls, ...(later.tool_calls ?? [])];
+        else if (calls.length) trailing = [...calls, ...trailing];
+      }
       const text =
         typeof message.content === 'string'
           ? message.content
@@ -1212,6 +1260,7 @@ export class Store {
       attempts: boundedAttempts,
       submissions: boundedSubmissions,
       messages: messages.reverse(),
+      ...(trailing.length ? { trailing_tool_calls: trailing } : {}),
       history_truncated: cursor !== null,
       approvals: this.approvals(id),
       operations: this.operations(id),

package/src/supervisor.ts

@@ -1,4 +1,5 @@
 import { BoardReads } from './board-reads.js';
+import { takeImages } from './mentions.js';
 import { HostBreaker, callThroughBreaker } from './host-breaker.js';
 import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
@@ -110,6 +111,28 @@ interface Worker {
   resolve: () => void;
   reject: (error: Error) => void;
 }
+/** Errors a local tool call returns to the model as feedback; any other one fails the worker.
+ * Every code src/local-edits.ts can throw belongs here (a failed replacement is not a crash). */
+export const LOCAL_TOOL_ERRORS = [
+  'local_busy',
+  'workspace_read_failed',
+  'unsafe_path',
+  'edit_mismatch',
+  'workspace_changed',
+  'workspace_busy',
+  'workspace_limit',
+  'workspace_conflict',
+  'not_found',
+  'binary_file',
+  'line_limit',
+  'invalid_field',
+  'request_conflict',
+  'command_conflict',
+  'command_limit',
+  'invalid_cursor',
+  'shell_binding',
+  'listen_unreachable',
+];
 export function processIdentity(pid: number): string | null {
   if (!Number.isSafeInteger(pid) || pid < 1) return null;
   try {
@@ -166,6 +189,33 @@ export function processIdentity(pid: number): string | null {
     return null;
   }
 }
+/**
+ * When a process started, keyed to this boot. Unlike processIdentity it survives exec, so it
+ * names a background task whose gated shell has since become the user's command.
+ */
+export function processStart(pid: number): string | null {
+  if (!Number.isSafeInteger(pid) || pid < 1) return null;
+  try {
+    if (process.platform === 'linux') {
+      const value = readFileSync(`/proc/${pid}/stat`, 'utf8');
+      const fields = value
+        .slice(value.lastIndexOf(') ') + 2)
+        .trim()
+        .split(/\s+/);
+      const boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+      return /^\d+$/.test(fields[19] ?? '') ? `linux-start-v1:${pid}:${boot}:${fields[19]}` : null;
+    }
+    const started = execFileSync('/bin/ps', ['-p', String(pid), '-o', 'lstart='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 2000,
+      killSignal: 'SIGKILL',
+    }).trim();
+    return started ? `ps-start-v1:${pid}:${started}` : null;
+  } catch {
+    return null;
+  }
+}
 function groupExists(pid: number): boolean {
   try {
     process.kill(-pid, 0);
@@ -177,6 +227,10 @@ function groupExists(pid: number): boolean {
 }
 export class Supervisor extends EventEmitter {
   localCoding?: import('./local-coding.js').LocalCoding;
+  /** Built-in web search and fetch for interactive coding (operator ruling 2026-10-31). */
+  web?: import('./web-search.js').WebSearch;
+  /** Desk-session hooks (Phase 4b); absent means none run. */
+  hooks?: import('./hooks.js').Hooks;
   tasks!: TaskContext;
   private compactionJobs = new Set<Promise<void>>();
   private readonly fetchBreaker = new HostBreaker();
@@ -558,6 +612,21 @@ export class Supervisor extends EventEmitter {
       });
       worker.pi.on('activity', (observation: import('./pi.js').ToolObservation) => {
         if (!worker.attempt || worker.stopping) return;
+        // PostToolUse runs after the tool and cannot change it; it is recorded like any hook.
+        if (observation.phase === 'finished' && this.hooks) {
+          const input = parsedInput(observation.input);
+          void this.hook(
+            id,
+            'PostToolUse',
+            {
+              tool_name: observation.tool,
+              tool_input: input,
+              tool_use_id: observation.tool_call_id,
+              tool_response: { output: observation.output ?? '', failed: !!observation.failed },
+            },
+            [observation.tool, ...hookAliases(observation.tool, input)],
+          ).catch(() => {});
+        }
         try {
           this.store.request(
             `tool-activity:${id}:${epoch}:${worker.attempt}`,
@@ -750,6 +819,44 @@ export class Supervisor extends EventEmitter {
     return w;
   }
   /** Is this attempt a task step that has acceptance checks to decide it? */
+  /** A person's own local coding session: not a delegated child and not AgentPod-admitted work,
+   * whose strict semantics stay as they are. */
+  isInteractiveCoding(id: string): boolean {
+    return this.interactiveCoding(id);
+  }
+  /** Run this desk session's hooks for `event`; other sessions (board, station, children) run none. */
+  private async hook(
+    id: string,
+    event: import('./hooks.js').HookEvent,
+    payload: Record<string, unknown>,
+    names: readonly string[] = [],
+  ): Promise<import('./hooks.js').HookOutcome | null> {
+    if (!this.hooks || !this.interactiveCoding(id)) return null;
+    return this.hooks.fire(id, event, payload, names);
+  }
+  /** A PreToolUse hook that blocks turns the tool call into an error the model reads. */
+  private async preToolUse(
+    id: string,
+    tool: string,
+    input: Record<string, unknown>,
+    toolCallId: string,
+  ): Promise<void> {
+    const out = await this.hook(
+      id,
+      'PreToolUse',
+      { tool_name: tool, tool_input: input, tool_use_id: toolCallId },
+      [tool, ...hookAliases(tool, input)],
+    );
+    if (out?.blocked)
+      throw new ServiceError('hook_blocked', `Blocked by a PreToolUse hook: ${out.blocked}`);
+  }
+  private interactiveCoding(id: string): boolean {
+    return (
+      this.store.localCoding(id) &&
+      !this.children?.owned(id) &&
+      !this.store.db.prepare('SELECT 1 FROM agentpod_admissions WHERE session_id=?').get(id)
+    );
+  }
   private checkedStepAttempt(attempt: string): boolean {
     const row = this.store.db
       .prepare('SELECT checks FROM task_steps WHERE attempt_id=?')
@@ -1123,6 +1230,83 @@ export class Supervisor extends EventEmitter {
         if (method === 'station.status') return this.station.view(c.id);
         throw new ServiceError('invalid_field', 'Unsupported station method');
       }
+      if (method === 'web.search' || method === 'web.fetch') {
+        if (!this.web || !this.store.localCoding(id) || this.children?.owned(id) || !w.attempt)
+          throw new ServiceError('web_denied', 'Web search is not admitted for this session', 403);
+        this.assertActive(id, w.epoch, w.attempt);
+        const args = object(body.args);
+        const toolCallId = string(body.tool_call_id, 'tool_call_id', 512);
+        await this.preToolUse(
+          id,
+          method === 'web.search' ? 'salaam_web_search' : 'salaam_web_fetch',
+          args,
+          toolCallId,
+        );
+        if (method === 'web.search') {
+          const out = await this.web.search({
+            query: string(args.query, 'query', 300),
+            ...(typeof args.kind === 'string'
+              ? { kind: args.kind as import('./web-search.js').SearchKind }
+              : {}),
+            ...(typeof args.limit === 'number' ? { limit: args.limit } : {}),
+          });
+          // Recorded: kind, backends tried, which answered and how long. Never a key or the query.
+          this.store.transaction(() =>
+            this.store.event(id, 'web.search', {
+              attempt_id: w.attempt,
+              tool_call_id: toolCallId,
+              kind: out.kind,
+              cached: !!out.cached,
+              results: out.results.length,
+              tried: out.tried,
+            }),
+          );
+          return out;
+        }
+        const url = string(args.url, 'url', 2000);
+        let host = '';
+        try {
+          host = new URL(url).hostname;
+        } catch {
+          /* fetchPage refuses it */
+        }
+        try {
+          const page = await (await import('./web-fetch.js')).fetchPage(url);
+          this.store.transaction(() =>
+            this.store.event(id, 'web.fetch', {
+              attempt_id: w.attempt,
+              tool_call_id: toolCallId,
+              host,
+              status: page.status,
+              chars: page.text.length,
+              truncated: page.truncated,
+            }),
+          );
+          const { renderFetched } = await import('./web-fetch.js');
+          return { ok: true, url: page.url, text: renderFetched(page) };
+        } catch (error) {
+          const message = String((error as Error).message ?? error).slice(0, 300);
+          this.store.transaction(() =>
+            this.store.event(id, 'web.fetch', {
+              attempt_id: w.attempt,
+              tool_call_id: toolCallId,
+              host,
+              error: message,
+            }),
+          );
+          return { ok: false, url, error: message };
+        }
+      }
+      if (method.startsWith('bgtask.')) {
+        if (!this.localCoding || !this.interactiveCoding(id) || !w.attempt)
+          throw new ServiceError('background_denied', 'Background commands are not admitted', 403);
+        this.assertActive(id, w.epoch, w.attempt);
+        if (method === 'bgtask.list') return { tasks: this.localCoding.tasks(id) };
+        const task = string(body.task_id, 'task_id', 64);
+        if (method === 'bgtask.output') return this.localCoding.taskOutput(id, task);
+        if (method === 'bgtask.stop') return this.localCoding.stopTask(id, task);
+        throw new ServiceError('invalid_field', 'Unsupported background task method');
+      }
       if (method.startsWith('local.') && method !== 'local.read') {
         if (
           !this.localCoding ||
@@ -1132,14 +1316,26 @@ export class Supervisor extends EventEmitter {
         )
           throw new ServiceError('local_denied', 'Local coding is not admitted', 403);
         this.assertActive(id, w.epoch, w.attempt);
-        if (method === 'local.prepare')
-          return this.localCoding.prepare(
+        if (method === 'local.prepare') {
+          const toolCall = string(body.tool_call_id, 'tool_call_id', 512);
+          const args = object(body.args);
+          // A retried prepare returns the recorded call; its hooks already ran.
+          const fresh = !this.localCoding.hasCall(id, w.epoch, toolCall);
+          if (fresh) await this.preToolUse(id, 'salaam_local', args, toolCall);
+          const prepared = await this.localCoding.prepareReviewed(
             id,
             w.epoch,
             w.attempt,
-            string(body.tool_call_id, 'tool_call_id', 512),
-            object(body.args),
+            toolCall,
+            args,
           );
+          if (fresh && prepared.approval?.state === 'pending')
+            void this.hook(id, 'Notification', {
+              notification_type: 'permission_prompt',
+              message: `Salaam needs your approval for a ${String(args.action ?? 'local')} request`,
+            }).catch(() => {});
+          return prepared;
+        }
         const c = this.localCoding.get(string(body.call_id, 'call_id'));
         if (c.session_id !== id || c.epoch !== w.epoch || c.attempt_id !== w.attempt)
           throw new ServiceError('local_scope', 'Operation belongs to another invocation', 403);
@@ -1153,6 +1349,12 @@ export class Supervisor extends EventEmitter {
         this.assertActive(id, w.epoch, w.attempt);
         this.store.taskGrantCheck?.(id);
         const args = object(body.args);
+        await this.preToolUse(
+          id,
+          'salaam_workspace',
+          args,
+          string(body.tool_call_id, 'tool_call_id', 512),
+        );
         const result = readLocalWorkspace(this.store.session(id).cwd, args);
         this.store.transaction(() =>
           this.store.event(id, 'workspace.read', {
@@ -1439,26 +1641,13 @@ export class Supervisor extends EventEmitter {
         ].includes(error.code)
       )
         throw error;
+      // A hook that blocked a tool call is the person's policy speaking, not a broken control: the
+      // model reads the reason as the tool's result (Phase 4b).
+      if (error instanceof ServiceError && error.code === 'hook_blocked') throw error;
       if (
         (method.startsWith('coding.') || method.startsWith('local.')) &&
         error instanceof ServiceError &&
-        [
-          'local_busy',
-          'workspace_read_failed',
-          'unsafe_path',
-          'workspace_changed',
-          'workspace_busy',
-          'workspace_limit',
-          'workspace_conflict',
-          'not_found',
-          'binary_file',
-          'line_limit',
-          'invalid_field',
-          'request_conflict',
-          'command_conflict',
-          'command_limit',
-          'invalid_cursor',
-        ].includes(error.code)
+        LOCAL_TOOL_ERRORS.includes(error.code)
       )
         throw error;
       if (
@@ -1510,6 +1699,7 @@ export class Supervisor extends EventEmitter {
     const state = {
       ...this.store.session(id),
       provider_route: this.store.providerRoute(id) ?? undefined,
+      project_instructions: this.tasks.instructions?.summary(id) ?? undefined,
       provider_capabilities:
         cap === undefined
           ? this.providerCapabilities()
@@ -1793,11 +1983,14 @@ export class Supervisor extends EventEmitter {
       // A checked task step is decided by its checks, not by a tool error the model went on
       // to recover from (operator decision, 2026-10-23). The error stays in the journal
       // (tool.finished failed=true). A delegated child turn, whose denied probes are its
-      // boundary proof, and any attempt outside a checked step still fail on it.
+      // boundary proof, and any attempt outside a checked step still fail on it, except an
+      // interactive coding turn: at a desk a failed command is feedback, and the turn is
+      // decided by how it ends (step 0, 2026-10-31).
       if (
         value.type === 'tool_execution_end' &&
         value.isError === true &&
-        (this.children?.owned(id) || !this.checkedStepAttempt(work.attempt.id))
+        (this.children?.owned(id) ||
+          (!this.checkedStepAttempt(work.attempt.id) && !this.interactiveCoding(id)))
       )
         outcome ??= {
           version: 1,
@@ -1807,7 +2000,33 @@ export class Supervisor extends EventEmitter {
     };
     w.pi.on('record', record);
     try {
-      const response = await w.pi.command('prompt', { message: work.submission.text });
+      // Interactive sessions pick up AGENTS.md edits at the start of each turn (recorded as a new
+      // instructions.loaded revision). A discovery failure never blocks the turn.
+      try {
+        this.tasks.instructions?.refresh(id);
+      } catch {
+        /* the previously loaded guidance stays in force */
+      }
+      // The folder as it was before this turn, so /rewind can return to it.
+      if (this.interactiveCoding(id)) this.tasks.checkpoints?.capture(id, work.attempt.id);
+      // UserPromptSubmit hooks may stop the prompt or add context to it (Phase 4b).
+      let message = work.submission.text;
+      const gate = await this.hook(id, 'UserPromptSubmit', { prompt: message });
+      if (gate?.blocked) {
+        this.store.finish(
+          work.attempt.id,
+          'failed',
+          null,
+          'Blocked by a UserPromptSubmit hook: ' + gate.blocked,
+        );
+        return true;
+      }
+      if (gate?.context) message += '\n\n<hook-context>\n' + gate.context + '\n</hook-context>';
+      const images = takeImages(this.store.db, work.submission.id);
+      const response = await w.pi.command('prompt', {
+        message,
+        ...(images.length ? { images } : {}),
+      });
       const disposition = object(response.data ?? {}).disposition;
       if (disposition !== 'started') throw new Error('Pi did not start the dispatched prompt');
       this.store.running(work.attempt.id);
@@ -1824,6 +2043,7 @@ export class Supervisor extends EventEmitter {
         { epoch: w.epoch, ...entries },
         outcome,
       );
+      void this.hook(id, 'Stop', { outcome: outcome ? 'failed' : 'completed' }).catch(() => {});
     } catch (error) {
       const message = redactFailureText((error as Error).message, w.secrets);
       if (!w.stopping && !this.store.cancelled(work.attempt.id))
@@ -1910,3 +2130,21 @@ export function toolFailureMessage(toolName: unknown): string {
     ? `Tool execution failed (tool ${toolName})`
     : 'Tool execution failed';
 }
+
+/** Claude Code names for Salaam's tools, so a `Bash` or `Edit|Write` matcher works unchanged. */
+export function hookAliases(tool: string, input: Record<string, unknown>): string[] {
+  if (tool === 'salaam_local')
+    return input.action === 'command' ? ['Bash'] : input.action === 'edit' ? ['Edit', 'Write'] : [];
+  if (tool === 'salaam_web_search') return ['WebSearch'];
+  if (tool === 'salaam_web_fetch') return ['WebFetch'];
+  if (tool === 'salaam_workspace') return ['Read'];
+  return [];
+}
+function parsedInput(input: string | undefined): Record<string, unknown> {
+  try {
+    const value = JSON.parse(input ?? '{}');
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch {
+    return {};
+  }
+}

package/src/task-context.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import type { TaskWork } from './task-work.js';
 import type { ContextAdmission } from './context-admission.js';
+import type { ProjectInstructions } from './project-instructions.js';
 import type { Store } from './store.js';
 import type { Artifacts } from './artifacts.js';
 import { canonical, ServiceError, string, integer, object } from './protocol.js';
@@ -41,6 +42,10 @@ export interface Compaction {
 export class TaskContext {
   work?: TaskWork;
   admitted?: ContextAdmission;
+  /** Interactive sessions only: AGENTS.md guidance loaded automatically (project-instructions.ts). */
+  instructions?: ProjectInstructions;
+  /** Interactive sessions only: a folder checkpoint before every turn (turn-rewind.ts). */
+  checkpoints?: import('./turn-rewind.js').TurnCheckpoints;
   constructor(
     readonly store: Store,
     readonly artifacts: Artifacts,
@@ -99,11 +104,13 @@ export class TaskContext {
     if (Buffer.byteLength(frame) > TASK_FRAME_BYTES)
       throw new ServiceError('context_capacity', 'Mandatory task state exceeds the context budget');
     const admittedContext = this.admitted?.frame(id);
-    return admittedContext
+    const projectInstructions = this.instructions?.frame(id);
+    return admittedContext || projectInstructions
       ? 'SALAAM_TASK_STATE ' +
           canonical({
             ...JSON.parse(frame.slice('SALAAM_TASK_STATE '.length)),
-            admitted_context: admittedContext,
+            ...(admittedContext ? { admitted_context: admittedContext } : {}),
+            ...(projectInstructions ? { project_instructions: projectInstructions } : {}),
           })
       : frame;
   }