@wichayutdew/pi-workflows 1.0.0 → 2.0.0

package/src/policy/bash-authorization.ts

@@ -1,10 +1,5 @@
 import { basename } from 'node:path';
 import type { BashPermission, BashRule } from '../config/types.ts';
-import {
-  authorizeHostedApiRead,
-  authorizeReadOnlyBash,
-  usesReadOnlyBashPreset,
-} from './bash-read-only.ts';
 import type { BashAuthorization } from './bash-types.ts';
 import { tokenizeRestrictedCommand } from './restricted-command.ts';
 
@@ -34,23 +29,15 @@ const matchesRule = (tokens: ReadonlyArray<string>, rule: BashRule): boolean =>
 /**
  * Authorizes a Bash command for a workflow step.
  *
- * Exact reviewed commands are considered first, followed by the configured
- * terminal mode and its static restrictions.
- *
  * @param command - Bash command text.
  * @param permission - Bash permission configured for the active step.
- * @param approvedCommands - Exact commands derived from a reviewed artifact.
  * @returns The authorization decision.
  */
 export const authorizeBash = (
   command: string,
   permission: BashPermission,
-  approvedCommands: ReadonlyArray<string> = [],
 ): BashAuthorization => {
-  const isReviewedCommand =
-    (permission.approvedSources?.length ?? 0) > 0 &&
-    approvedCommands.includes(command);
-  if (isReviewedCommand || permission.mode === 'unrestricted') {
+  if (permission.mode === 'unrestricted') {
     return { allowed: true };
   }
   if (permission.mode === 'deny') {
@@ -70,17 +57,11 @@ export const authorizeBash = (
     return reject('environment assignments are not allowed in restricted mode');
   }
 
-  if (permission.mode === 'read-only') {
-    return authorizeReadOnlyBash(parsed.tokens);
-  }
-
   const rule = permission.allow.find((candidate) =>
     matchesRule(parsed.tokens, candidate),
   );
   if (!rule) {
     return reject("command does not match this step's Bash allow-list");
   }
-  return usesReadOnlyBashPreset(parsed.tokens)
-    ? authorizeReadOnlyBash(parsed.tokens)
-    : authorizeHostedApiRead(parsed.tokens);
+  return { allowed: true, tokens: [...parsed.tokens] };
 };

package/src/policy/bash-types.ts

@@ -13,8 +13,3 @@ export type RestrictedCommandTokens =
       readonly tokens?: never;
       readonly error: string;
     };
-
-export type RestrictedGitCommand = {
-  readonly subcommand: string;
-  readonly subcommandIndex: number;
-};

package/src/policy/bash.ts

@@ -1,4 +1,3 @@
 export { authorizeBash } from './bash-authorization.ts';
-export type { BashAuthorization, RestrictedGitCommand } from './bash-types.ts';
+export type { BashAuthorization } from './bash-types.ts';
 export { tokenizeRestrictedCommand } from './restricted-command.ts';
-export { parseRestrictedGitCommand } from './restricted-git.ts';

package/src/policy/tool-call-authorization.ts

@@ -19,7 +19,6 @@ const reject = (reason: string): ToolAuthorization => ({
  * @param input - Requested tool input.
  * @param step - Active workflow step.
  * @param inventory - Registered tool inventory.
- * @param approvedBashCommands - Exact commands derived from human review.
  * @returns The authorization decision.
  */
 export const authorizeToolCall = (
@@ -27,7 +26,6 @@ export const authorizeToolCall = (
   input: Readonly<Record<string, unknown>>,
   step: WorkflowStep,
   inventory: ReadonlyArray<ToolInventoryItem>,
-  approvedBashCommands: ReadonlyArray<string> = [],
 ): ToolAuthorization => {
   if (toolName === 'mcp') {
     return authorizeMcpProxy(input, step.permissions.mcp);
@@ -47,11 +45,7 @@ export const authorizeToolCall = (
   if (typeof command !== 'string') {
     return reject('Bash call is missing command text');
   }
-  const result = authorizeBash(
-    command,
-    step.permissions.bash,
-    approvedBashCommands,
-  );
+  const result = authorizeBash(command, step.permissions.bash);
   return result.allowed
     ? { allowed: true }
     : reject(result.reason ?? 'Bash command is not allowed');

package/src/preflight.ts

@@ -87,11 +87,6 @@ export function preflightStep(
       hasResource: (toolName) => toolNames.has(toolName),
       resourceKind: 'tool',
     }),
-    ...(step.permissions.mcp.length > 0 && !toolNames.has('mcp')
-      ? [
-          'MCP selectors are configured, but the "mcp" proxy tool is not installed',
-        ]
-      : []),
     ...(isPlannotatorRequired && !hasExtension('plannotator')
       ? [
           'Plannotator is required by this gate, but its extension is not installed or detectable',

package/src/prompt/retry-task.ts

@@ -46,6 +46,9 @@ export function automaticRecoveryTask(
   maxAttempts: number,
 ): string {
   const diagnostics = serializeDiagnostics(reasons);
+  const missingStructuredOutput = reasons.some((reason) =>
+    reason.includes('Missing structured_output call'),
+  );
 
   return [
     '## Automatic recovery after subagent failure',
@@ -57,10 +60,15 @@ export function automaticRecoveryTask(
     '</pi-workflows-retry-diagnostic-v1>',
     '',
     'Diagnose and resolve the specific causes before completing the original step. Treat every listed approach as already attempted. When `Failed tool`, `Command` or `Arguments`, and `Tool error` are present, use them to choose a permitted alternative; do not repeat a failing call unchanged.',
-    'This is a continuation, not a blind replay. Inspect current repository and external state first, assume a prior call may already have applied its effect, and do not repeat a side effect that is already present.',
-    'Keep working after a successful recovery and complete the original step; do not return a pause outcome merely because the first call failed.',
+    'This is a continuation, not a blind replay. Inspect current state first, assume a prior call may already have applied its effect, and do not repeat a side effect that is already present.',
+    'Keep working after a successful recovery and complete the original step according to its configured prompt and outcomes.',
+    ...(missingStructuredOutput
+      ? [
+          'A prior child ended without the required `structured_output` call. After completing the original work, call `structured_output` exactly once as the only tool call in its message; a prose final response does not complete this workflow step.',
+        ]
+      : []),
     'Use only tools enabled for this step. If the named tool is unavailable, use an enabled alternative. In restricted Bash modes, use one allowed command per tool call; do not use shell operators, substitutions, escapes in double quotes, environment assignments, or wrappers.',
-    'If no permitted alternative resolves the failure, follow the step outcome contract: use `retry` for another safe attempt or `replan` for an authority change when those outcomes are offered. Use a pause outcome only after those routes cannot resolve it, and include the exact failed call, exact error, alternatives attempted, and why they could not resolve it.',
+    'If no permitted alternative resolves the failure, follow the step prompt when choosing a configured outcome; the engine assigns no special meaning to outcome names. Include the exact failed call, exact error, alternatives attempted, and observed state in the handoff.',
   ].join('\n');
 }
 

package/src/prompt/step-contract.ts

@@ -9,7 +9,7 @@ export type StepContract = {
   readonly outcomes: ReadonlyArray<string>;
   readonly transitionLines: string;
   readonly gateLine: string;
-  readonly recoveryInstructions: ReadonlyArray<string>;
+  readonly workspaceLines: ReadonlyArray<string>;
 };
 
 type CreateStepContractOptions = {
@@ -18,57 +18,8 @@ type CreateStepContractOptions = {
   readonly step: WorkflowStep;
 };
 
-const pauseOutcomesFor = (
-  step: WorkflowStep,
-  allowedOutcomeSet: ReadonlySet<string>,
-): ReadonlyArray<string> =>
-  Object.entries(step.transitions)
-    .filter(
-      ([outcome, target]) =>
-        target === '$pause' && allowedOutcomeSet.has(outcome),
-    )
-    .map(([outcome]) => outcome);
-
-type RecoveryInstructionsOptions = {
-  readonly allowedOutcomeSet: ReadonlySet<string>;
-  readonly pauseOutcomes: ReadonlyArray<string>;
-};
-
-const buildRecoveryInstructions = ({
-  allowedOutcomeSet,
-  pauseOutcomes,
-}: RecoveryInstructionsOptions): ReadonlyArray<string> => {
-  const retryInstruction = allowedOutcomeSet.has('retry')
-    ? [
-        'Use outcome `retry` when the execution contract remains valid and another bounded fresh attempt can safely continue from inspected state. Include the exact failure, attempts, observed state, and next alternative in `summary`.',
-      ]
-    : [];
-  const replanInstruction = allowedOutcomeSet.has('replan')
-    ? [
-        'Use outcome `replan` when recovery requires a material change to reviewed intent, commands, targets, or authority. Include the exact invalid contract evidence and proposed correction in `summary`.',
-      ]
-    : [];
-
-  if (pauseOutcomes.length > 0) {
-    return [
-      ...retryInstruction,
-      ...replanInstruction,
-      `Use a pause outcome (${pauseOutcomes.join(', ')}) only when permitted alternatives and offered recovery outcomes cannot resolve the workflow definition, environment, or execution contract. Describe the exhausted recovery evidence declaratively in \`summary\`.`,
-    ];
-  }
-  if (allowedOutcomeSet.has('retry') || allowedOutcomeSet.has('replan')) {
-    return [...retryInstruction, ...replanInstruction];
-  }
-
-  return [
-    ...retryInstruction,
-    ...replanInstruction,
-    'If the workflow definition, environment, or final execution contract is wrong, do not fabricate success or call the completion tool; end with a concise declarative error so the harness pauses the step.',
-  ];
-};
-
 /**
- * Derives the completion and recovery contract for an active workflow step.
+ * Derives the completion contract for an active workflow step.
  *
  * @param options - Workflow state used to resolve currently allowed outcomes.
  * @returns Immutable text fragments for the step prompt.
@@ -80,7 +31,6 @@ export function createStepContract({
 }: CreateStepContractOptions): StepContract {
   const outcomes = allowedOutcomes(workflow, run);
   const allowedOutcomeSet = new Set(outcomes);
-  const pauseOutcomes = pauseOutcomesFor(step, allowedOutcomeSet);
   const transitionLines = Object.entries(step.transitions)
     .filter(([outcome]) => allowedOutcomeSet.has(outcome))
     .map(([outcome, target]) => `- ${outcome}: ${target}`)
@@ -88,14 +38,18 @@ export function createStepContract({
   const gateLine = step.gate
     ? `- ${step.gate.submitOutcome}: submit the artifact to ${step.gate.provider}; include the full artifact argument`
     : '';
+  const workspaceLines = step.workspace
+    ? [
+        `Workspace-binding outcomes: ${step.workspace.bindOn.join(', ')}`,
+        `For those outcomes, include \`workspace.cwd\` as an absolute directory under one allowed root relative to the run-start directory: ${step.workspace.allowedRoots.join(', ')}`,
+        'For every other outcome, omit `workspace`.',
+      ]
+    : ['This step cannot bind a workspace; omit `workspace`.'];
 
   return {
     outcomes,
     transitionLines,
     gateLine,
-    recoveryInstructions: buildRecoveryInstructions({
-      allowedOutcomeSet,
-      pauseOutcomes,
-    }),
+    workspaceLines,
   };
 }

package/src/prompt/step-sections.ts

@@ -30,6 +30,11 @@ export function buildResourceSection({
     `Extension selectors: ${formatList(step.permissions.extensions)}`,
     `Skills: ${formatList(step.permissions.skills)}`,
     `Bash policy: ${step.permissions.bash.mode}`,
+    `Bash allow rules: ${
+      step.permissions.bash.allow.length > 0
+        ? JSON.stringify(step.permissions.bash.allow)
+        : '(none)'
+    }`,
     '',
     `Use only the listed skills for this step. Tool calls are enforced ${isDelegated ? 'inside this child process' : 'by the workflow harness'}.`,
     '',
@@ -59,17 +64,10 @@ export function buildDelegatedHandoffSection(
  * @param step - Active delegated workflow step.
  * @returns Delegated completion-guidance lines.
  */
-export function buildDelegatedCompletionInstructions(
-  step: WorkflowStep,
-): ReadonlyArray<string> {
-  const finalContractInstruction = step.gate
-    ? 'Put every unresolved decision in the gate artifact with evidence, options, a recommendation, and an adopted default; do not ask a terminal question.'
-    : 'Treat the step instructions and incoming handoff as the final execution contract; do not ask a terminal question.';
-
+export function buildDelegatedCompletionInstructions(): ReadonlyArray<string> {
   return [
     'This child is non-interactive. Never call `contact_supervisor`, `subagent_supervisor`, or `intercom`.',
-    'When a tool or command fails, inspect its exact error, diagnose the cause, and try a permitted semantically equivalent alternative before ending the step. Continue the original work after recovery; do not treat the first recoverable failure as terminal.',
-    'Never broaden mutation targets or external side effects while recovering. Before using a pause outcome, exhaust safe permitted alternatives and include the exact failed call, exact error, alternatives attempted, observed state, and why recovery is impossible.',
-    finalContractInstruction,
+    'Follow the step instructions when choosing one valid outcome; outcome names have no built-in domain meaning.',
+    'Stay within the configured permissions and do not broaden mutation targets or external side effects.',
   ];
 }

package/src/prompt/step-task.ts

@@ -45,6 +45,8 @@ type RenderStepPromptOptions = {
   readonly execution: StepExecution;
 };
 
+const RESUME_INPUT_PLACEHOLDER = /\{\{\s*resume\.input\s*\}\}/;
+
 const renderStepPrompt = ({
   workflow,
   run,
@@ -53,20 +55,44 @@ const renderStepPrompt = ({
 }: RenderStepPromptOptions): string => {
   const promptTemplate = workflow.prompts[run.currentStepId] ?? '';
   const templateValues = createTemplateValues({ workflow, run, step });
-  const hidesRepeatedHandoff =
+  const hidesRepeatedLastSummary =
     execution === 'delegated' &&
     /\{\{\s*last\.summary\s*\}\}/.test(promptTemplate);
-  const values = hidesRepeatedHandoff
-    ? {
-        ...templateValues,
-        'last.summary':
-          '(Provided once in the Previous step handoff section below.)',
-      }
-    : templateValues;
+  const handoffReference =
+    '(Provided once in the Previous step handoff section below.)';
+  const values = {
+    ...templateValues,
+    ...(hidesRepeatedLastSummary ? { 'last.summary': handoffReference } : {}),
+  };
 
   return renderTemplate(promptTemplate, values);
 };
 
+const buildResumeInputSection = (
+  run: WorkflowRun,
+  promptContainsResumeInput: boolean,
+): ReadonlyArray<string> => {
+  if (!run.resumeInput) return [];
+  const authority =
+    'The user-supplied resume guidance for this attempt is authoritative when it conflicts with task instructions in the step prompt or previous handoff. Inspect current state before applying it. It does not change the workflow graph or the YAML-enforced tools, MCP, extensions, skills, Bash policy, or workspace boundary.';
+  if (promptContainsResumeInput) {
+    return ['## Resume guidance authority', '', authority, ''];
+  }
+  const serialized = JSON.stringify({ input: run.resumeInput }, null, 2)
+    .replaceAll('<', '\\u003c')
+    .replaceAll('>', '\\u003e');
+  return [
+    '## User guidance supplied with `/workflow-resume`',
+    '',
+    authority,
+    '',
+    '<pi-workflows-resume-input-v1>',
+    serialized,
+    '</pi-workflows-resume-input-v1>',
+    '',
+  ];
+};
+
 /**
  * Builds the complete task for either a main-agent or delegated workflow step.
  *
@@ -77,6 +103,7 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
   const { execution, workflow, run } = options;
   const step = resolveStep(workflow, run);
   const isDelegated = execution === 'delegated';
+  const promptTemplate = workflow.prompts[run.currentStepId] ?? '';
   const prompt = renderStepPrompt({ workflow, run, step, execution });
   const handoff = currentStepHandoff(run);
   const contract = createStepContract({ workflow, run, step });
@@ -105,6 +132,10 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     prompt,
     '',
     ...(isDelegated ? buildDelegatedHandoffSection(handoff) : []),
+    ...buildResumeInputSection(
+      run,
+      RESUME_INPUT_PLACEHOLDER.test(promptTemplate),
+    ),
     ...buildResourceSection({ execution, step }),
     '## Completion contract',
     '',
@@ -112,11 +143,11 @@ export function buildStepTask(options: BuildStepTaskOptions): string {
     `Valid outcomes: ${contract.outcomes.join(', ')}`,
     contract.transitionLines,
     contract.gateLine,
+    ...contract.workspaceLines,
     '',
     'Put a self-contained compact handoff in `summary`; this is the only step context passed to the next fresh child.',
-    ...(isDelegated ? buildDelegatedCompletionInstructions(step) : []),
+    ...(isDelegated ? buildDelegatedCompletionInstructions() : []),
     'Do not call the completion tool alongside other tool calls.',
-    ...contract.recoveryInstructions,
   ].join('\n');
 }
 

package/src/prompt/template.ts

@@ -7,7 +7,7 @@ import type { WorkflowRun } from '../engine/state.ts';
 export type TemplateValues = Readonly<Record<string, string>>;
 
 /**
- * Combines the approved incoming handoff with the latest paused-attempt
+ * Combines the incoming handoff with the latest paused-attempt
  * summary without duplicating identical content.
  *
  * @param run - Current workflow run.
@@ -24,7 +24,7 @@ export function currentStepHandoff(run: WorkflowRun): string {
   }
 
   return [
-    'Incoming approved or previous-step handoff:',
+    'Incoming previous-step handoff:',
     incomingHandoff,
     '',
     'Latest paused attempt:',
@@ -76,6 +76,9 @@ export function createTemplateValues({
     'step.id': run.currentStepId,
     'step.title': step.title,
     'last.summary': currentStepHandoff(run),
+    'reviewed.artifact': run.reviewedArtifact ?? '',
+    'reviewed.feedback': run.reviewedFeedback ?? '',
     'gate.feedback': run.gateFeedback,
+    'resume.input': run.resumeInput ?? '',
   };
 }

package/src/runtime/completion-tool.ts

@@ -1,4 +1,5 @@
 import { Type } from 'typebox';
+import { MAX_WORKSPACE_PATH_CHARS } from '../config/types.ts';
 
 export const WORKFLOW_COMPLETION_TOOL = 'workflow_complete_step';
 
@@ -20,6 +21,19 @@ export const WORKFLOW_COMPLETION_PARAMETERS = Type.Object(
         maxLength: 200_000,
       }),
     ),
+    workspace: Type.Optional(
+      Type.Object(
+        {
+          cwd: Type.String({
+            description:
+              'Absolute working directory established for subsequent workflow steps',
+            minLength: 1,
+            maxLength: MAX_WORKSPACE_PATH_CHARS,
+          }),
+        },
+        { additionalProperties: false },
+      ),
+    ),
   },
   { additionalProperties: false },
 );

package/src/runtime/main-step-completion.ts

@@ -52,6 +52,9 @@ export function registerMainStepCompletion({
           ...(params.artifact !== undefined
             ? { artifact: params.artifact }
             : {}),
+          ...(params.workspace !== undefined
+            ? { workspace: { cwd: params.workspace.cwd } }
+            : {}),
         },
         activeExecution,
       );

package/src/runtime/main-step-policy.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { WORKFLOW_COMPLETION_TOOL } from './completion-tool.ts';
+import { armMainStepTrace } from './main-step-trace.ts';
 import type {
   MainStepRuntimeDependencies,
   MainStepRuntimeState,
@@ -26,6 +27,7 @@ export function registerMainStepPolicy({
   });
 
   pi.on('message_end', (event) => {
+    armMainStepTrace(state, event.message);
     if (!state.active) {
       return;
     }
@@ -70,7 +72,6 @@ export function registerMainStepPolicy({
       Object.fromEntries(Object.entries(event.input)),
       state.active.step,
       pi.getAllTools(),
-      state.active.approvedBashCommands,
     );
     if (!authorization.allowed) {
       return {

package/src/runtime/main-step-runtime-types.ts

@@ -17,8 +17,14 @@ export type MainStepExecution = StepResultPolicy & {
   readonly runId: string;
   readonly stepId: string;
   readonly stepDigest: string;
+  /** Exact task whose finalized user message arms this attempt's trace. */
+  readonly task: string;
   readonly step: WorkflowStep;
-  readonly approvedBashCommands: ReadonlyArray<string>;
+  /** Persists one finalized, already-redacted turn before Pi begins a later turn. */
+  readonly onTrace: (
+    lines: ReadonlyArray<string>,
+    context: ExtensionContext,
+  ) => Promise<void> | void;
   /** Handles the captured result after Pi fully settles the agent run. */
   readonly onSettled: (
     result: WorkflowStepResult | undefined,
@@ -60,5 +66,7 @@ export type MainStepRuntimeState = {
   active: MainStepExecution | undefined;
   pendingResult: WorkflowStepResult | undefined;
   invalidCompletionCalls: ReadonlySet<string>;
+  traceArmed: boolean;
+  traceClosed: boolean;
   isSuspended: boolean;
 };

package/src/runtime/main-step-runtime.ts

@@ -5,6 +5,7 @@ import { authorizeToolCall, resolveActiveTools } from '../policy/tools.ts';
 import { registerMainStepCompletion } from './main-step-completion.ts';
 import { registerMainStepLifecycle } from './main-step-lifecycle.ts';
 import { registerMainStepPolicy } from './main-step-policy.ts';
+import { registerMainStepTrace } from './main-step-trace.ts';
 import type {
   MainStepExecution,
   MainStepRuntimeController,
@@ -84,6 +85,7 @@ export function createMainStepRuntime({
 
   registerMainStepLifecycle({ pi, state });
   registerMainStepPolicy({ pi, state, dependencies });
+  registerMainStepTrace({ pi, state });
   registerMainStepCompletion({ pi, state, dependencies });
 
   return {

package/src/runtime/main-step-state.ts

@@ -14,6 +14,8 @@ export function createMainStepRuntimeState(): MainStepRuntimeState {
     active: undefined,
     pendingResult: undefined,
     invalidCompletionCalls: new Set(),
+    traceArmed: false,
+    traceClosed: false,
     isSuspended: false,
   };
 }
@@ -43,6 +45,8 @@ export function activateMainStep({
   state.active = execution;
   state.pendingResult = undefined;
   state.invalidCompletionCalls = new Set();
+  state.traceArmed = false;
+  state.traceClosed = false;
 }
 
 /**
@@ -56,6 +60,8 @@ export function deactivateMainStep(state: MainStepRuntimeState): boolean {
   state.active = undefined;
   state.pendingResult = undefined;
   state.invalidCompletionCalls = new Set();
+  state.traceArmed = false;
+  state.traceClosed = false;
   return wasActive;
 }
 

package/src/runtime/main-step-trace.ts

@@ -0,0 +1,45 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { stepLogLinesFromTurn, textOnlyUserMessage } from '../step-log.ts';
+import type { MainStepRuntimeState } from './main-step-runtime-types.ts';
+
+type RegisterMainStepTraceOptions = {
+  readonly pi: ExtensionAPI;
+  readonly state: MainStepRuntimeState;
+};
+
+/** Arms a trace only after Pi finalizes the exact extension-supplied task. */
+export function armMainStepTrace(
+  state: MainStepRuntimeState,
+  message: unknown,
+): void {
+  if (!state.active || state.traceArmed || state.traceClosed) return;
+  if (textOnlyUserMessage(message) === state.active.task) {
+    state.traceArmed = true;
+  }
+}
+
+/**
+ * Persists finalized main-agent turns while one exact workflow attempt is armed.
+ *
+ * Successful completion is closed only after its assistant call and tool result
+ * are captured, preventing queued parent-session follow-ups from leaking in.
+ */
+export function registerMainStepTrace({
+  pi,
+  state,
+}: RegisterMainStepTraceOptions): void {
+  pi.on('turn_end', async (event, context) => {
+    const active = state.active;
+    if (!active || !state.traceArmed || state.traceClosed) return;
+    const lines = stepLogLinesFromTurn(event.message, event.toolResults);
+    try {
+      if (lines.length > 0) await active.onTrace(lines, context);
+    } catch {
+      // Status evidence is best-effort and must never interrupt the agent loop.
+    } finally {
+      if (state.active === active && state.pendingResult) {
+        state.traceClosed = true;
+      }
+    }
+  });
+}

package/src/runtime/step-result.ts

@@ -1,3 +1,9 @@
+import { isAbsolute } from 'node:path';
+import {
+  MAX_WORKSPACE_PATH_CHARS,
+  type StepWorkspaceBinding,
+} from '../config/types.ts';
+
 const MAX_ARTIFACT_CHARS = 200_000;
 const RESULT_KEYS = new Set([
   'version',
@@ -5,6 +11,7 @@ const RESULT_KEYS = new Set([
   'outcome',
   'summary',
   'artifact',
+  'workspace',
 ]);
 
 /**
@@ -15,6 +22,11 @@ export type StepResultPolicy = {
   readonly outcomes: ReadonlyArray<string>;
   readonly summaryMaxChars: number;
   readonly gateSubmitOutcome?: string;
+  readonly workspace?: StepWorkspaceBinding;
+};
+
+export type WorkflowResultWorkspace = {
+  readonly cwd: string;
 };
 
 /**
@@ -26,12 +38,51 @@ export type WorkflowStepResult = {
   readonly outcome: string;
   readonly summary: string;
   readonly artifact?: string;
+  readonly workspace?: WorkflowResultWorkspace;
 };
 
 const isObject = (value: unknown): value is Record<string, unknown> => {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 };
 
+function parseResultWorkspace(
+  value: unknown,
+  outcome: string,
+  policy: StepResultPolicy,
+): WorkflowResultWorkspace | undefined {
+  const requiresWorkspace = policy.workspace?.bindOn.includes(outcome) === true;
+  if (!requiresWorkspace) {
+    if (value !== undefined) {
+      throw new Error('workflow step workspace is forbidden for this outcome');
+    }
+    return undefined;
+  }
+  if (!isObject(value)) {
+    throw new Error(
+      `workflow step outcome "${outcome}" requires workspace.cwd`,
+    );
+  }
+  const unknownKey = Object.keys(value).find((key) => key !== 'cwd');
+  if (unknownKey) {
+    throw new Error(
+      `workflow step workspace has unknown property "${unknownKey}"`,
+    );
+  }
+  if (typeof value.cwd !== 'string') {
+    throw new Error('workflow step workspace cwd must be a string');
+  }
+  const cwd = value.cwd;
+  if (!cwd || cwd.includes('\0') || !isAbsolute(cwd)) {
+    throw new Error('workflow step workspace cwd must be an absolute path');
+  }
+  if (cwd.length > MAX_WORKSPACE_PATH_CHARS) {
+    throw new Error(
+      `workflow step workspace cwd exceeds ${MAX_WORKSPACE_PATH_CHARS} characters`,
+    );
+  }
+  return { cwd };
+}
+
 /**
  * Validates and normalizes the structured result returned by a workflow step.
  *
@@ -96,11 +147,17 @@ export function parseWorkflowStepResult(
   ) {
     throw new Error('workflow gate outcome requires a non-empty artifact');
   }
+  const workspace = parseResultWorkspace(
+    value.workspace,
+    value.outcome,
+    policy,
+  );
   return {
     version: 1,
     policyDigest: policy.policyDigest,
     outcome: value.outcome,
     summary,
     ...(artifact !== undefined ? { artifact } : {}),
+    ...(workspace ? { workspace } : {}),
   };
 }