@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/supervisor.js

@@ -1,12 +1,16 @@
+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';
 import { EventEmitter } from 'node:events';
-import { mkdirSync, existsSync, writeFileSync, readFileSync, readlinkSync } from 'node:fs';
+import { mkdirSync, existsSync, writeFileSync, readFileSync, readlinkSync, rmSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { PROTOCOL_VERSION, canonical, object, ServiceError, textDigest, workerTools, workerCapabilities, string, } from './protocol.js';
 import { PI_CLI, HOUSE_EXTENSION, POLICY_DIGEST, bundleDigest, VERSION, PI_VERSION, } from './config.js';
 import { readinessFingerprint } from './readiness-fingerprint.js';
 import { PiProcess, PiCommandError } from './pi.js';
+import { mergeMcpProvenance } from './operator-mcp.js';
 import { OFFLINE_ROUTE, providerRoute, providerHasOutputCap, } from './provider-config.js';
 import { validateApiKey } from './credentials.js';
 import { resolveProviderAuth } from './provider-auth.js';
@@ -16,6 +20,28 @@ import { digest } from './protocol.js';
 import { readLocalWorkspace } from './local-workspace.js';
 import { repositoryPath } from './repository-snapshots.js';
 import { acpFailure, credentialStrings, parseAcpFailure, providerOutcome, redactFailureText, toolMetadata, } from './acp-outcome.js';
+/** 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) {
     if (!Number.isSafeInteger(pid) || pid < 1)
         return null;
@@ -37,7 +63,18 @@ export function processIdentity(pid) {
                     throw Error('Invalid process start identity');
                 return { start: fields[19], group: fields[2], session: fields[3] };
             };
-            const before = stat(), boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(), executable = readlinkSync(path + '/exe'), argv = readFileSync(path + '/cmdline');
+            const before = stat(), boot = readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim(), 
+            // A tools-user launcher (sudo) is root-owned; its exe link is unreadable to the service.
+            executable = (() => {
+                try {
+                    return readlinkSync(path + '/exe');
+                }
+                catch (error) {
+                    if (error.code === 'EACCES')
+                        return 'unreadable';
+                    throw error;
+                }
+            })(), argv = readFileSync(path + '/cmdline');
             if (!/^[a-f0-9-]{36}$/.test(boot) ||
                 !argv.length ||
                 argv.length > 16384 ||
@@ -58,6 +95,35 @@ export function processIdentity(pid) {
         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) {
+    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) {
     try {
         process.kill(-pid, 0);
@@ -73,10 +139,18 @@ export class Supervisor extends EventEmitter {
     store;
     options;
     localCoding;
+    /** Built-in web search and fetch for interactive coding (operator ruling 2026-10-31). */
+    web;
+    /** Desk-session hooks (Phase 4b); absent means none run. */
+    hooks;
     tasks;
     compactionJobs = new Set();
+    fetchBreaker = new HostBreaker();
     managed;
     mcp;
+    operatorMcp;
+    /** Item 9: the host's pinned persona, given to every worker on this host. */
+    persona;
     toolkit;
     station;
     children;
@@ -118,7 +192,26 @@ export class Supervisor extends EventEmitter {
         const child = this.children?.owned(id);
         if (child)
             return JSON.parse(child.authority);
-        return workerTools(!!this.options.effectsEnabled, !!this.children?.owned(id), this.codingBinding(id), undefined, !!this.mcp, !!this.toolkit, !!this.station, this.store.localWorkspace(id), this.store.localCoding(id));
+        return workerTools(!!this.options.effectsEnabled, !!this.children?.owned(id), this.codingBinding(id), undefined, !!this.mcp, !!this.toolkit, !!this.station, this.store.localWorkspace(id), this.store.localCoding(id), this.declaredMcp(id));
+    }
+    /** Operator-declared MCP reaches root sessions only; children get no MCP authority. */
+    declaredMcp(id) {
+        return !!this.operatorMcp && !this.operatorMcp.empty && !this.children?.owned(id);
+    }
+    /** Every MCP server the session got, from both sources; persisted beside the worker. */
+    mcpServers(id) {
+        const live = this.workers.get(id)?.mcpServers;
+        if (live)
+            return structuredClone(live);
+        try {
+            const path = join(this.options.stateDir, 'workers', id, 'mcp-servers.json');
+            return existsSync(path)
+                ? JSON.parse(readFileSync(path, 'utf8'))
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     childBoundary(id, epoch) {
         const child = this.children?.owned(id);
@@ -149,6 +242,10 @@ export class Supervisor extends EventEmitter {
     }
     bootId = randomUUID();
     workers = new Map();
+    boardReadsStore;
+    get boardReads() {
+        return (this.boardReadsStore ??= new BoardReads(this.store));
+    }
     monitor;
     bundle;
     constructor(store, options) {
@@ -276,6 +373,18 @@ export class Supervisor extends EventEmitter {
                 worker.mcp = await this.mcp.ready(id);
             if (this.toolkit && !child)
                 worker.toolkit = await this.toolkit.ready(id);
+            if (this.declaredMcp(id))
+                worker.operatorMcp = this.operatorMcp.provenance();
+            if (worker.operatorMcp || worker.mcp) {
+                // Collisions are refused at admission; nothing is silently shadowed.
+                worker.mcpServers = mergeMcpProvenance(worker.operatorMcp ?? [], (worker.mcp?.servers ?? []).map((server) => ({
+                    name: server.name,
+                    source: 'agentpod',
+                    transport: 'http',
+                    endpoint_digest: server.endpoint_digest,
+                    declaration_digest: digest(server),
+                })));
+            }
             if (this.station && !child)
                 worker.station = this.station.ready(id);
             this.store.execution.assert(id);
@@ -290,6 +399,11 @@ export class Supervisor extends EventEmitter {
             }), { mode: 0o600 });
             const sessionDir = join(workerDir, 'sessions');
             mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+            const provenancePath = join(workerDir, 'mcp-servers.json');
+            if (worker.mcpServers)
+                writeFileSync(provenancePath, JSON.stringify(worker.mcpServers, null, 2), { mode: 0o600 });
+            else
+                rmSync(provenancePath, { force: true });
             const config = {
                 socket: this.options.bridgeSocket,
                 token: worker.token,
@@ -306,8 +420,11 @@ export class Supervisor extends EventEmitter {
                 local: this.store.localWorkspace(id),
                 localCoding: this.store.localCoding(id),
                 ...(worker.mcp ? { mcp: worker.mcp } : {}),
+                ...(worker.operatorMcp ? { operator_mcp: worker.operatorMcp } : {}),
+                ...(worker.mcpServers ? { mcp_servers: worker.mcpServers } : {}),
                 ...(worker.toolkit ? { toolkit: worker.toolkit } : {}),
                 ...(worker.station ? { station: worker.station } : {}),
+                ...(this.persona ? { persona: this.persona } : {}),
             };
             const args = [
                 PI_CLI,
@@ -368,6 +485,16 @@ export class Supervisor extends EventEmitter {
             worker.pi.on('activity', (observation) => {
                 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}`, `${observation.phase}:${observation.tool_call_id}`, observation, () => {
                         this.store.event(id, `tool.${observation.phase}`, {
@@ -543,6 +670,58 @@ 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) {
+        return this.interactiveCoding(id);
+    }
+    /** Run this desk session's hooks for `event`; other sessions (board, station, children) run none. */
+    async hook(id, event, payload, names = []) {
+        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. */
+    async preToolUse(id, tool, input, toolCallId) {
+        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}`);
+    }
+    interactiveCoding(id) {
+        return (this.store.localCoding(id) &&
+            !this.children?.owned(id) &&
+            !this.store.db.prepare('SELECT 1 FROM agentpod_admissions WHERE session_id=?').get(id));
+    }
+    checkedStepAttempt(attempt) {
+        const row = this.store.db
+            .prepare('SELECT checks FROM task_steps WHERE attempt_id=?')
+            .get(attempt);
+        try {
+            const checks = row?.checks ? JSON.parse(String(row.checks)) : [];
+            return Array.isArray(checks) && checks.length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** A station call refused before it runs leaves no station_calls row, so record its
+     * method, requested action and refusal code: never its path, arguments or content. */
+    recordStationRefusal(id, method, body, error) {
+        const args = body.args && typeof body.args === 'object' ? body.args : {};
+        const ident = (v) => typeof v === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(v) ? v : null;
+        try {
+            this.store.transaction(() => this.store.event(id, 'station.call_refused', {
+                attempt_id: this.workers.get(id)?.attempt ?? null,
+                method: ident(method),
+                action: ident(args.action),
+                code: error instanceof ServiceError ? ident(error.code) : 'error',
+            }));
+        }
+        catch {
+            // Recording a refusal never changes the refusal itself.
+        }
+    }
     async bridge(id, method, token, body) {
         const w = this.authenticate(id, token, body);
         const route = w.route;
@@ -587,8 +766,14 @@ export class Supervisor extends EventEmitter {
                     context_digest: textDigest(w.frame),
                     ...(boundary ? { worker_binding: boundary } : {}),
                     ...(w.mcp ? { mcp: w.mcp } : {}),
+                    ...(w.operatorMcp ? { operator_mcp: w.operatorMcp } : {}),
+                    ...(w.mcpServers
+                        ? { mcp_servers: w.mcpServers, mcp_servers_digest: digest(w.mcpServers) }
+                        : {}),
                     ...(w.toolkit ? { toolkit: w.toolkit } : {}),
                     ...(w.station ? { station: w.station } : {}),
+                    // Item 9: the worker proves it runs with the host's pinned persona.
+                    ...(this.persona ? { persona_digest: this.persona.digest } : {}),
                 };
                 for (const [key, value] of Object.entries(expected))
                     if (canonical(body[key]) !== canonical(value))
@@ -680,6 +865,45 @@ export class Supervisor extends EventEmitter {
                 w.secrets = [...new Set([...(w.secrets ?? []), ...credentialStrings(auth)])];
                 return auth;
             }
+            if (method.startsWith('operator_mcp.')) {
+                if (!this.declaredMcp(id) || !w.operatorMcp || !w.attempt)
+                    throw new ServiceError('mcp_disabled', 'Worker has no declared MCP servers', 403);
+                this.assertActive(id, w.epoch, w.attempt);
+                if (method === 'operator_mcp.catalog')
+                    return await this.operatorMcp.catalog(id, body.server, body.tool);
+                if (method !== 'operator_mcp.call')
+                    throw new ServiceError('invalid_field', 'Unknown declared MCP method', 400);
+                const attempt = w.attempt;
+                const args = body.arguments ?? {};
+                const server = String(body.server ?? ''), tool = String(body.tool ?? '');
+                // A host failing again and again is paused briefly (never called, so no operator MCP call
+                // is recorded); the agent gets a tool error and the run carries on.
+                return await callThroughBreaker(this.fetchBreaker, id, args, (paused) => this.store.transaction(() => this.store.event(id, 'fetch.host_paused', { attempt_id: attempt, ...paused })), async () => {
+                    try {
+                        const result = await this.operatorMcp.call(id, body.server, body.tool, args);
+                        this.store.transaction(() => this.store.event(id, 'operator_mcp.call', {
+                            attempt_id: attempt,
+                            server,
+                            tool,
+                            argument_digest: digest(args),
+                            outcome: result.is_error ? 'tool_error' : 'returned',
+                            result_digest: digest(result),
+                        }));
+                        return result;
+                    }
+                    catch (error) {
+                        this.store.transaction(() => this.store.event(id, 'operator_mcp.call', {
+                            attempt_id: attempt,
+                            server,
+                            tool,
+                            argument_digest: digest(args),
+                            outcome: 'failed',
+                            error: error.code ?? 'mcp_server_failed',
+                        }));
+                        throw error;
+                    }
+                });
+            }
             if (method.startsWith('toolkit.')) {
                 if (!this.toolkit || !w.toolkit || !w.attempt || this.children?.owned(id))
                     throw new ServiceError('toolkit_disabled', 'Worker has no native Toolkit authority', 403);
@@ -732,6 +956,15 @@ export class Supervisor extends EventEmitter {
                         : {}),
                 };
             }
+            if (method === 'board.read' || method === 'board.status') {
+                // Read-only board reads, served by the hub (operator ruling 2026-10-28, option iii).
+                if (!this.station || !w.station || !w.attempt || this.children?.owned(id))
+                    throw new ServiceError('station_disabled', 'Board reads need protected station work');
+                this.assertActive(id, w.epoch, w.attempt);
+                return method === 'board.read'
+                    ? this.boardReads.request(id, string(body.tool_call_id, 'tool_call_id', 512), object(body.args))
+                    : this.boardReads.get(id, string(body.read_id, 'read_id', 64));
+            }
             if (method.startsWith('station.')) {
                 if (!this.station || !w.station || !w.attempt || this.children?.owned(id))
                     throw new ServiceError('station_disabled', 'Station execution is unavailable');
@@ -750,6 +983,77 @@ export class Supervisor extends EventEmitter {
                     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 }
+                            : {}),
+                        ...(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.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 ||
                     !this.store.localCoding(id) ||
@@ -757,8 +1061,21 @@ export class Supervisor extends EventEmitter {
                     !w.attempt)
                     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(id, w.epoch, w.attempt, string(body.tool_call_id, 'tool_call_id', 512), object(body.args));
+                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, 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);
@@ -774,6 +1091,7 @@ 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', {
                     attempt_id: w.attempt,
@@ -948,6 +1266,8 @@ export class Supervisor extends EventEmitter {
         }
         catch (error) {
             this.store.taskBudgetDenied?.(id, error);
+            if (method.startsWith('station.'))
+                this.recordStationRefusal(id, method, body, error);
             if (method.startsWith('station.') &&
                 error instanceof ServiceError &&
                 [
@@ -960,6 +1280,16 @@ export class Supervisor extends EventEmitter {
                     'not_found',
                 ].includes(error.code))
                 throw error;
+            if (method.startsWith('operator_mcp.') &&
+                error instanceof ServiceError &&
+                [
+                    'invalid_field',
+                    'invalid_mcp_server',
+                    'invalid_mcp_tool',
+                    'invalid_mcp_arguments',
+                    'mcp_server_failed',
+                ].includes(error.code))
+                throw error;
             if ((method.startsWith('mcp.') || method.startsWith('toolkit.')) &&
                 error instanceof ServiceError &&
                 [
@@ -989,25 +1319,13 @@ export class Supervisor extends EventEmitter {
                     'request_conflict',
                 ].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 (method === 'history' &&
                 error instanceof ServiceError &&
@@ -1055,6 +1373,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()
                 : {
@@ -1064,6 +1383,7 @@ export class Supervisor extends EventEmitter {
                         ? null
                         : 'No provider-enforced output cap; tasks must explicitly disable token budgeting',
                 },
+            ...(this.mcpServers(id) ? { mcp_servers: this.mcpServers(id) } : {}),
         };
         const w = this.workers.get(id);
         if (w?.invalid)
@@ -1317,16 +1637,49 @@ export class Supervisor extends EventEmitter {
                         outcome = candidate;
                 }
             }
-            if (value.type === 'tool_execution_end' && value.isError === true)
+            // 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, 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.interactiveCoding(id))))
                 outcome ??= {
                     version: 1,
                     stopReason: 'error',
-                    failure: acpFailure(new ServiceError('tool_failed', 'Tool execution failed')),
+                    failure: acpFailure(new ServiceError('tool_failed', toolFailureMessage(value.toolName))),
                 };
         };
         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');
@@ -1338,6 +1691,7 @@ export class Supervisor extends EventEmitter {
             const result = object((await w.pi.command('get_last_assistant_text')).data);
             this.childBoundary(id, w.epoch);
             this.store.finish(work.attempt.id, outcome ? 'failed' : 'completed', String(result.text ?? ''), outcome?.failure?.message ?? null, { epoch: w.epoch, ...entries }, outcome);
+            void this.hook(id, 'Stop', { outcome: outcome ? 'failed' : 'completed' }).catch(() => { });
         }
         catch (error) {
             const message = redactFailureText(error.message, w.secrets);
@@ -1386,6 +1740,7 @@ export class Supervisor extends EventEmitter {
         try {
             this.managed?.invalidateWorker(w.id, w.epoch);
             this.cancelMcpWorker(w);
+            void this.operatorMcp?.stopSession(w.id).catch(() => { });
             this.children?.workerLost(w.id, 'Worker stopped before child dispatch');
         }
         catch {
@@ -1414,3 +1769,31 @@ export class Supervisor extends EventEmitter {
             throw new AggregateError(errors, 'Worker shutdown could not persist all final states');
     }
 }
+/** Names the failing tool (never its arguments or output), so a failed step says which call
+ * failed it. Only a plain tool identifier is echoed. */
+export function toolFailureMessage(toolName) {
+    return typeof toolName === 'string' && /^[A-Za-z0-9_.:-]{1,64}$/.test(toolName)
+        ? `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, input) {
+    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) {
+    try {
+        const value = JSON.parse(input ?? '{}');
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}