ai-foreman 1.7.2 → 1.7.4

package/dist/adapters/claude.d.ts

@@ -1,12 +1,14 @@
+import type { PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 /** Lazy-load the Claude Agent SDK. Throws an actionable error if not installed. */
 export declare function requireClaudeSDK(): Promise<typeof import("@anthropic-ai/claude-agent-sdk")>;
-import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, ProviderSettingSwitch, TurnResult } from "./types.js";
+import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult, ContextUsage, PermissionDecision, ProviderSettingSwitch, TurnResult } from "./types.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
  * `canUseTool` is omitted here — it's a closure that the constructor adds.
  */
 export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions, "permission">): Record<string, unknown>;
+export declare function permissionDecisionToClaudeResult(decision: PermissionDecision, toolUseID?: string): PermissionResult;
 /**
  * Drives Claude Code through the Claude Agent SDK in streaming-input mode:
  * one persistent session, follow-up turns pushed as user messages, permission

package/dist/adapters/claude.js

@@ -37,6 +37,22 @@ export function buildClaudeQueryOptions(opts) {
     }
     return base;
 }
+export function permissionDecisionToClaudeResult(decision, toolUseID) {
+    if (decision.behavior === "allow") {
+        return {
+            behavior: "allow",
+            updatedInput: decision.updatedInput,
+            updatedPermissions: decision.updatedPermissions,
+            toolUseID,
+        };
+    }
+    return {
+        behavior: "deny",
+        message: decision.message,
+        interrupt: decision.interrupt,
+        toolUseID,
+    };
+}
 /**
  * Drives Claude Code through the Claude Agent SDK in streaming-input mode:
  * one persistent session, follow-up turns pushed as user messages, permission
@@ -81,11 +97,19 @@ export class ClaudeAdapter {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
                 stderr: (data) => this.captureStderr(data),
-                canUseTool: async (toolName, input) => {
-                    const decision = await opts.permission({ toolName, input });
-                    return decision.behavior === "allow"
-                        ? { behavior: "allow" }
-                        : { behavior: "deny", message: decision.message };
+                canUseTool: async (toolName, input, requestOptions = {}) => {
+                    const decision = await opts.permission({
+                        toolName,
+                        input,
+                        signal: requestOptions.signal,
+                        title: requestOptions.title,
+                        displayName: requestOptions.displayName,
+                        description: requestOptions.description,
+                        decisionReason: requestOptions.decisionReason,
+                        blockedPath: requestOptions.blockedPath,
+                        toolUseID: requestOptions.toolUseID,
+                    });
+                    return permissionDecisionToClaudeResult(decision, requestOptions.toolUseID);
                 },
             },
         });

package/dist/adapters/types.d.ts

@@ -8,13 +8,30 @@ export interface PermissionRequest {
     input: Record<string, unknown>;
     /** Human-readable prompt from the agent, when available. */
     title?: string;
+    /** Signaled if the provider-side operation should be aborted. */
+    signal?: AbortSignal;
+    /** Provider-native identifier for this specific tool call, when available. */
+    toolUseID?: string;
+    /** Short provider-rendered name for the requested action, when available. */
+    displayName?: string;
+    /** Provider-rendered detail for the requested action, when available. */
+    description?: string;
+    /** Provider explanation for why permission was requested, when available. */
+    decisionReason?: string;
+    /** Provider path that triggered the permission request, when available. */
+    blockedPath?: string;
 }
 /** The foreman's verdict on a permission request. */
 export type PermissionDecision = {
     behavior: "allow";
+    /** Provider-native tool input to continue with after host interaction. */
+    updatedInput?: Record<string, unknown>;
+    /** Provider-native permission updates to apply after approval. */
+    updatedPermissions?: Array<Record<string, unknown>>;
 } | {
     behavior: "deny";
     message: string;
+    interrupt?: boolean;
 };
 /** Decides each permission request. Supplied by the foreman, called by the adapter. */
 export type PermissionHandler = (req: PermissionRequest) => Promise<PermissionDecision>;

package/dist/agentRun.d.ts

@@ -4,6 +4,7 @@ import { type StepStatus } from "./foreman.js";
 import type { BuilderAdapter, BuilderAdapterOptions, EffortLevel, TurnResult } from "./adapters/types.js";
 import { type RoleBundle } from "./roles.js";
 import type { AgentRuntime } from "./runtimeAuth.js";
+import type { AgentRoleDefaultsV1 } from "rafi-spec";
 export type { EffortLevel } from "./adapters/types.js";
 export declare const VALID_EFFORT: readonly EffortLevel[];
 export interface RoleBuilderOptions {
@@ -54,4 +55,5 @@ export declare function makeLogPath(projectDir: string, label: string): string;
 export declare function mergeSkills(roleSkills: readonly string[], extraSkills?: readonly string[]): string[];
 export declare function readOnlyPermissionConfig(): PermissionConfig;
 export declare function createRoleBuilder(opts: RoleBuilderOptions): Promise<RoleBuilder>;
+export declare function readRoleDefaultsForExecution(projectDir: string, role: string): AgentRoleDefaultsV1 | undefined;
 export declare function runRoleInstruction(opts: RoleInstructionRunOptions): Promise<RoleInstructionRunResult>;

package/dist/agentRun.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, DEFAULT_CONFIG } from "./config.js";
 import { Log } from "./log.js";
@@ -86,7 +86,7 @@ export async function createRoleBuilder(opts) {
     if (!existsSync(opts.projectDir)) {
         throw new Error(`project directory not found: ${opts.projectDir}`);
     }
-    const saved = readRoleDefaults(opts.projectDir, opts.role);
+    const saved = readRoleDefaultsForExecution(opts.projectDir, opts.role);
     const configuredEffort = saved?.reasoning && saved.reasoning !== "default" ? saved.reasoning : undefined;
     const effectiveEffort = opts.effort ?? (VALID_EFFORT.includes(configuredEffort) ? configuredEffort : undefined);
     assertEffortLevel(effectiveEffort);
@@ -107,6 +107,7 @@ export async function createRoleBuilder(opts) {
     let runtimeExecutable = ready.executable;
     const policy = new PermissionPolicy(opts.permissionConfig ?? config.permissions, opts.projectDir);
     const skills = mergeSkills(roleBundle.skills, opts.extraSkills);
+    const interactive = !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
     const makeAdapter = async (nextRuntime, resumeSessionId) => {
         const adapterOpts = {
             cwd: opts.projectDir,
@@ -114,7 +115,7 @@ export async function createRoleBuilder(opts) {
             runtimePhase: phaseForRole(opts.role),
             model,
             resumeSessionId,
-            permission: createPermissionHandler(policy, log),
+            permission: createPermissionHandler(policy, log, { interactive }),
             effort,
             fast: opts.fast ?? saved?.fast,
             sandboxMode: opts.sandboxMode,
@@ -130,7 +131,7 @@ export async function createRoleBuilder(opts) {
         initial,
         runtime,
         label: opts.label,
-        enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        enabled: interactive,
         allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId,
         recreate: async (nextRuntime, resumeSessionId) => {
             const nextReady = await ensureRuntimeReadyForCommand(opts.projectDir, nextRuntime, {
@@ -157,20 +158,47 @@ function phaseForRole(role) {
         return "uninstaller";
     return "builder";
 }
-function readRoleDefaults(projectDir, role) {
+export function readRoleDefaultsForExecution(projectDir, role) {
     const path = join(projectDir, "rafi-config.yaml");
     if (!existsSync(path))
         return undefined;
     try {
         const config = parseYaml(readFileSync(path, "utf8"));
-        return config?.agent_defaults?.version === 1
+        const saved = config?.agent_defaults?.version === 1
             ? config.agent_defaults.roles[role]
             : undefined;
+        if (!saved)
+            return undefined;
+        if (isFullyInitializedTracker(projectDir))
+            return saved;
+        const { make: _pendingMake, ...active } = saved;
+        return active;
     }
     catch {
         return undefined;
     }
 }
+function isFullyInitializedTracker(projectDir) {
+    try {
+        const trackerPath = join(projectDir, ".tickets", "config.yaml");
+        const ticketsPath = join(projectDir, ".tickets", "tickets.yaml");
+        const statePath = join(projectDir, ".tickets", "ticket-state.sqlite");
+        if (!existsSync(trackerPath) || !existsSync(ticketsPath) || !existsSync(statePath))
+            return false;
+        const tracker = parseYaml(readFileSync(trackerPath, "utf8"));
+        if (!tracker || typeof tracker !== "object" || Array.isArray(tracker))
+            return false;
+        const tickets = parseYaml(readFileSync(ticketsPath, "utf8"));
+        if (!tickets || !Array.isArray(tickets.tickets))
+            return false;
+        if (!statSync(statePath).isFile())
+            return false;
+        return readFileSync(statePath).subarray(0, 16).toString("utf8") === "SQLite format 3\u0000";
+    }
+    catch {
+        return false;
+    }
+}
 export async function runRoleInstruction(opts) {
     const logPath = opts.logPath ?? makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-"));
     const log = new Log(logPath);

package/dist/foreman.d.ts

@@ -36,7 +36,9 @@ export declare function buildQaFixInstruction(issues: string): string;
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
 export declare function buildPlanningTurn(n: number, ticketsContent?: string): string;
 /** Builds the permission callback: classify, log, allow or escalate. */
-export declare function createPermissionHandler(policy: PermissionPolicy, log: Log): PermissionHandler;
+export declare function createPermissionHandler(policy: PermissionPolicy, log: Log, opts?: {
+    interactive?: boolean;
+}): PermissionHandler;
 export interface BatchResult {
     completed: number;
     requested: number;

package/dist/foreman.js

@@ -1,5 +1,6 @@
 import { select, isCancel } from "@clack/prompts";
 import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
+import { countProviderQuestions, handleProviderQuestionTool } from "./providerQuestions.js";
 import { fireNotification } from "./notify.js";
 import { isTicketsInitialized, loadTicketsConfig } from "./tickets/config.js";
 import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
@@ -166,8 +167,20 @@ export function buildPlanningTurn(n, ticketsContent) {
     return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order. Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; output the numbered list only. Do not emit a STEP_STATUS marker on this turn.`;
 }
 /** Builds the permission callback: classify, log, allow or escalate. */
-export function createPermissionHandler(policy, log) {
+export function createPermissionHandler(policy, log, opts = {}) {
     return async (req) => {
+        const providerQuestion = await handleProviderQuestionTool(req, {
+            interactive: opts.interactive ?? true,
+        });
+        if (providerQuestion) {
+            log.write("permission", {
+                tool: req.toolName,
+                decision: providerQuestion.behavior,
+                reason: "provider question prompt",
+                questionCount: countProviderQuestions(req.input),
+            });
+            return providerQuestion;
+        }
         const verdict = policy.classify(req);
         log.write("permission", {
             tool: req.toolName,

package/dist/providerQuestions.d.ts

@@ -0,0 +1,14 @@
+import { isCancel, multiselect, select, text } from "@clack/prompts";
+import type { PermissionDecision, PermissionRequest } from "./adapters/types.js";
+export interface ProviderQuestionPromptDeps {
+    select: typeof select;
+    multiselect: typeof multiselect;
+    text: typeof text;
+    isCancel: typeof isCancel;
+}
+export interface ProviderQuestionOptions {
+    interactive: boolean;
+    prompts?: ProviderQuestionPromptDeps;
+}
+export declare function handleProviderQuestionTool(req: PermissionRequest, opts: ProviderQuestionOptions): Promise<PermissionDecision | undefined>;
+export declare function countProviderQuestions(input: Record<string, unknown>): number;

package/dist/providerQuestions.js

@@ -0,0 +1,192 @@
+import { isCancel, multiselect, select, text } from "@clack/prompts";
+const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+const CUSTOM_VALUE = "__rafi_custom_response__";
+export async function handleProviderQuestionTool(req, opts) {
+    if (req.toolName !== ASK_USER_QUESTION_TOOL)
+        return undefined;
+    if (!opts.interactive) {
+        return {
+            behavior: "deny",
+            interrupt: true,
+            message: "AskUserQuestion requires interactive input, but this Rafi run is non-interactive.",
+        };
+    }
+    const questions = parseQuestions(req.input);
+    if (questions.length === 0) {
+        return {
+            behavior: "deny",
+            interrupt: true,
+            message: "AskUserQuestion did not include any readable questions.",
+        };
+    }
+    const prompts = opts.prompts ?? { select, multiselect, text, isCancel };
+    const answers = recordFromUnknown(req.input.answers);
+    const annotations = annotationRecordFromUnknown(req.input.annotations);
+    for (const question of questions) {
+        const answered = await askOneQuestion(question, prompts, req.signal);
+        if (answered.cancelled) {
+            return {
+                behavior: "deny",
+                interrupt: true,
+                message: "User cancelled the provider question prompt.",
+            };
+        }
+        answers[question.question] = answered.answer;
+        if (answered.annotation)
+            annotations[question.question] = answered.annotation;
+    }
+    const updatedInput = {
+        ...req.input,
+        answers,
+    };
+    if (Object.keys(annotations).length > 0)
+        updatedInput.annotations = annotations;
+    return { behavior: "allow", updatedInput };
+}
+export function countProviderQuestions(input) {
+    const questions = input.questions;
+    return Array.isArray(questions) ? questions.length : 0;
+}
+function parseQuestions(input) {
+    const rawQuestions = input.questions;
+    if (!Array.isArray(rawQuestions))
+        return [];
+    return rawQuestions.flatMap((raw) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return [];
+        const record = raw;
+        const question = typeof record.question === "string" ? record.question.trim() : "";
+        if (!question)
+            return [];
+        const header = typeof record.header === "string" && record.header.trim()
+            ? record.header.trim()
+            : undefined;
+        const options = Array.isArray(record.options)
+            ? record.options.flatMap((option) => {
+                if (!option || typeof option !== "object" || Array.isArray(option))
+                    return [];
+                const optionRecord = option;
+                const label = typeof optionRecord.label === "string" ? optionRecord.label.trim() : "";
+                if (!label)
+                    return [];
+                return [{
+                        label,
+                        description: typeof optionRecord.description === "string" ? optionRecord.description : undefined,
+                        preview: typeof optionRecord.preview === "string" ? optionRecord.preview : undefined,
+                    }];
+            })
+            : [];
+        return [{ question, header, options, multiSelect: record.multiSelect === true }];
+    });
+}
+async function askOneQuestion(question, prompts, signal) {
+    const message = question.header ? `${question.header}: ${question.question}` : question.question;
+    if (question.options.length === 0) {
+        const answer = await prompts.text({ message, signal });
+        if (prompts.isCancel(answer))
+            return { cancelled: true, answer: "" };
+        return { cancelled: false, answer: String(answer) };
+    }
+    if (question.multiSelect) {
+        const selected = await prompts.multiselect({
+            message,
+            options: [
+                ...question.options.map((option, index) => ({
+                    value: String(index),
+                    label: option.label,
+                    hint: option.description,
+                })),
+                { value: CUSTOM_VALUE, label: "Custom response", hint: "Type a different answer" },
+            ],
+            required: true,
+            signal,
+        });
+        if (prompts.isCancel(selected))
+            return { cancelled: true, answer: "" };
+        const selectedValues = selected;
+        const labels = selectedValues
+            .filter((value) => value !== CUSTOM_VALUE)
+            .map((value) => question.options[Number(value)]?.label)
+            .filter((value) => Boolean(value));
+        const previews = selectedValues
+            .filter((value) => value !== CUSTOM_VALUE)
+            .map((value) => question.options[Number(value)]?.preview)
+            .filter((value) => Boolean(value));
+        let notes;
+        if (selectedValues.includes(CUSTOM_VALUE)) {
+            const custom = await prompts.text({ message: "Custom response:", signal });
+            if (prompts.isCancel(custom))
+                return { cancelled: true, answer: "" };
+            notes = String(custom);
+            labels.push(notes);
+        }
+        return {
+            cancelled: false,
+            answer: labels.join(", "),
+            annotation: annotationFor(previews, notes),
+        };
+    }
+    const selected = await prompts.select({
+        message,
+        options: [
+            ...question.options.map((option, index) => ({
+                value: String(index),
+                label: option.label,
+                hint: option.description,
+            })),
+            { value: CUSTOM_VALUE, label: "Custom response", hint: "Type a different answer" },
+        ],
+        signal,
+    });
+    if (prompts.isCancel(selected))
+        return { cancelled: true, answer: "" };
+    if (selected === CUSTOM_VALUE) {
+        const custom = await prompts.text({ message: "Custom response:", signal });
+        if (prompts.isCancel(custom))
+            return { cancelled: true, answer: "" };
+        const answer = String(custom);
+        return { cancelled: false, answer, annotation: { notes: answer } };
+    }
+    const option = question.options[Number(selected)];
+    return {
+        cancelled: false,
+        answer: option?.label ?? String(selected),
+        annotation: annotationFor(option?.preview ? [option.preview] : [], undefined),
+    };
+}
+function annotationFor(previews, notes) {
+    const annotation = {};
+    if (previews.length > 0)
+        annotation.preview = previews.join("\n\n");
+    if (notes)
+        annotation.notes = notes;
+    return Object.keys(annotation).length > 0 ? annotation : undefined;
+}
+function recordFromUnknown(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (typeof entry === "string")
+            result[key] = entry;
+    }
+    return result;
+}
+function annotationRecordFromUnknown(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return {};
+    const result = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const annotation = {};
+        if (typeof record.preview === "string")
+            annotation.preview = record.preview;
+        if (typeof record.notes === "string")
+            annotation.notes = record.notes;
+        if (Object.keys(annotation).length > 0)
+            result[key] = annotation;
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",