ultracode-for-codex 0.2.0 → 0.2.1

package/README.md

@@ -26,7 +26,7 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.0.tgz
+npm install --save-dev /path/to/ultracode-for-codex-0.2.1.tgz
 ```
 
 Run a workflow:
@@ -118,6 +118,10 @@ want Codex to auto-load the package boundaries and verification routine.
 - The only production backend is Codex app-server over stdio.
 - Direct provider credentials are stripped from the Codex child process
   environment.
+- Codex subagents run against the requested workflow cwd and receive bounded
+  read-only workspace tools for text file reads and directory listings.
+- Built-in `code-review` injects deterministic workspace context before calling
+  its subagent so file-specific prompts carry local evidence into the review.
 - Workflow execution is local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.

package/ULTRACODE_INSTALL.md

@@ -31,7 +31,7 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.0.tgz
+npm install --save-dev ./ultracode-for-codex-0.2.1.tgz
 ```
 
 Optional Codex companion skill:
@@ -104,6 +104,10 @@ Useful controls:
 - Keep stdout reserved for the final JSON result; stream progress records to
   stderr as JSONL unless a human chooses `--progress plain`.
 - Strip direct provider credentials from child CLI environments.
+- Run Codex subagents against the requested workflow cwd and provide bounded
+  read-only workspace tools for text file reads and directory listings.
+- Built-in `code-review` adds deterministic workspace context before the agent
+  call, prioritizing files explicitly mentioned in the prompt.
 - Install consumers from a packaged artifact.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned

package/dist/codex/subagent-backend.d.ts

@@ -30,6 +30,7 @@ export declare class CodexSubagentBackend implements SubagentBackend {
     private readonly pending;
     private readonly turnWaiters;
     private readonly bufferedTurnStates;
+    private readonly threadReadRoots;
     private isolation;
     constructor(options: CodexSubagentBackendOptions);
     generate(request: SubagentRequest, signal?: AbortSignal): Promise<SubagentResult>;
@@ -43,6 +44,10 @@ export declare class CodexSubagentBackend implements SubagentBackend {
     private notify;
     private handleLine;
     private respondToServerRequest;
+    private writeResponse;
+    private handleDynamicToolCall;
+    private readWorkspaceFile;
+    private listWorkspaceDirectory;
     private handleNotification;
     private waitForTurn;
     private markWaiterCompleted;

package/dist/codex/subagent-backend.js

@@ -1,8 +1,8 @@
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import readline from 'node:readline';
 import { codexDefaultReasoningEffort, codexDefaultVerbosity, } from '../settings.js';
 import { estimateTokens } from '../runtime/types.js';
@@ -10,6 +10,9 @@ import { codexChildProcessEnv } from './env.js';
 const USAGE_NOTIFICATION_GRACE_MS = 100;
 const BUFFERED_TURN_STATE_TTL_MS = 30_000;
 const FALLBACK_CODEX_MODEL = 'gpt-5.5';
+const WORKSPACE_DYNAMIC_TOOL_NAMESPACE = 'workspace';
+const MAX_WORKSPACE_TOOL_READ_BYTES = 200_000;
+const MAX_WORKSPACE_TOOL_DIRECTORY_ENTRIES = 200;
 const DISABLED_CODEX_CONTEXT_FEATURES = [
     'apps',
     'browser_use',
@@ -22,6 +25,46 @@ const DISABLED_CODEX_CONTEXT_FEATURES = [
     'shell_tool',
     'workspace_dependencies',
 ];
+const WORKSPACE_DYNAMIC_TOOLS = [
+    {
+        type: 'namespace',
+        name: WORKSPACE_DYNAMIC_TOOL_NAMESPACE,
+        description: 'Read-only access to files in the active workflow workspace.',
+        tools: [
+            {
+                type: 'function',
+                name: 'read_file',
+                description: 'Read a UTF-8 text file inside the active workflow workspace.',
+                inputSchema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Relative path inside the active workspace.',
+                        },
+                    },
+                    required: ['path'],
+                },
+            },
+            {
+                type: 'function',
+                name: 'list_directory',
+                description: 'List direct entries in a directory inside the active workflow workspace.',
+                inputSchema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Relative directory path inside the active workspace. Defaults to the workspace root.',
+                        },
+                    },
+                },
+            },
+        ],
+    },
+];
 export class CodexSubagentBackend {
     name = 'codex-subagent';
     model;
@@ -39,6 +82,7 @@ export class CodexSubagentBackend {
     pending = new Map();
     turnWaiters = new Map();
     bufferedTurnStates = new Map();
+    threadReadRoots = new Map();
     isolation = null;
     constructor(options) {
         this.command = options.command ?? 'codex';
@@ -70,7 +114,7 @@ export class CodexSubagentBackend {
         if (signal)
             signal.addEventListener('abort', onAbort, { once: true });
         try {
-            const cwd = request.worktreePath ?? this.isolation?.workDir ?? this.cwd;
+            const cwd = request.worktreePath ?? this.cwd;
             threadId = await this.startThread(reasoningEffort, this.verbosity, Boolean(structuredTool), cwd, Boolean(request.worktreePath));
             const turn = await this.send('turn/start', {
                 threadId,
@@ -121,6 +165,7 @@ export class CodexSubagentBackend {
         }
         this.turnWaiters.clear();
         this.clearBufferedTurnStates();
+        this.threadReadRoots.clear();
         this.lineReader?.close();
         this.child?.kill('SIGTERM');
         this.child = null;
@@ -192,7 +237,7 @@ export class CodexSubagentBackend {
             approvalPolicy: 'never',
             sandbox: workspaceWrite ? 'workspace-write' : 'read-only',
             environments: [],
-            dynamicTools: [],
+            dynamicTools: WORKSPACE_DYNAMIC_TOOLS,
             ephemeral: true,
             baseInstructions: 'Ultracode workflow subagent. Produce only the workflow agent return value.',
             developerInstructions: structured
@@ -211,9 +256,11 @@ export class CodexSubagentBackend {
         const threadId = readPath(thread, ['result', 'thread', 'id']);
         if (!threadId)
             throw new Error('codex app-server did not return a thread id');
+        this.threadReadRoots.set(threadId, await realpath(cwd).catch(() => resolve(cwd)));
         return threadId;
     }
     archiveThread(threadId) {
+        this.threadReadRoots.delete(threadId);
         void this.send('thread/archive', { threadId }).catch(() => undefined);
     }
     async cleanupIsolation() {
@@ -267,20 +314,104 @@ export class CodexSubagentBackend {
             return;
         }
         if (id !== null && typeof message.method === 'string') {
-            this.respondToServerRequest(id, message.method);
+            this.respondToServerRequest(id, message.method, message.params);
             return;
         }
         if (typeof message.method === 'string')
             this.handleNotification(message.method, message.params);
     }
-    respondToServerRequest(id, method) {
-        const result = method.includes('requestApproval') ? { decision: 'decline' } : undefined;
-        this.child?.stdin.write(`${JSON.stringify({
-            id,
-            ...(result
-                ? { result }
-                : { error: { code: -32601, message: `Unsupported server request: ${method}` } }),
-        })}\n`);
+    respondToServerRequest(id, method, params) {
+        void (async () => {
+            if (method.includes('requestApproval')) {
+                this.writeResponse(id, { result: { decision: 'decline' } });
+                return;
+            }
+            if (method === 'item/tool/call') {
+                this.writeResponse(id, { result: await this.handleDynamicToolCall(params) });
+                return;
+            }
+            this.writeResponse(id, {
+                error: { code: -32601, message: `Unsupported server request: ${method}` },
+            });
+        })().catch((err) => {
+            this.writeResponse(id, {
+                error: { code: -32603, message: workflowToolErrorMessage(err) },
+            });
+        });
+    }
+    writeResponse(id, response) {
+        this.child?.stdin.write(`${JSON.stringify({ id, ...response })}\n`);
+    }
+    async handleDynamicToolCall(params) {
+        const data = asRecord(params);
+        const threadId = typeof data?.threadId === 'string' ? data.threadId : '';
+        const root = this.threadReadRoots.get(threadId);
+        if (!root)
+            return dynamicToolFailure('Workspace root is unavailable for this thread.');
+        const namespace = data?.namespace === null || typeof data?.namespace === 'string'
+            ? data.namespace
+            : null;
+        const rawTool = typeof data?.tool === 'string' ? data.tool : '';
+        const tool = namespace === WORKSPACE_DYNAMIC_TOOL_NAMESPACE
+            ? rawTool
+            : namespace === null && (rawTool === 'read_file' || rawTool === 'list_directory')
+                ? rawTool
+                : rawTool.startsWith(`${WORKSPACE_DYNAMIC_TOOL_NAMESPACE}.`)
+                    ? rawTool.slice(WORKSPACE_DYNAMIC_TOOL_NAMESPACE.length + 1)
+                    : '';
+        const args = asRecord(data?.arguments) ?? {};
+        if (tool === 'read_file') {
+            return await this.readWorkspaceFile(root, args).catch((err) => dynamicToolFailure(workflowToolErrorMessage(err)));
+        }
+        if (tool === 'list_directory') {
+            return await this.listWorkspaceDirectory(root, args).catch((err) => dynamicToolFailure(workflowToolErrorMessage(err)));
+        }
+        return dynamicToolFailure(`Unsupported workspace tool: ${namespace ? `${namespace}.` : ''}${rawTool}`);
+    }
+    async readWorkspaceFile(root, args) {
+        const requestedPath = typeof args.path === 'string' ? args.path : '';
+        if (!requestedPath.trim())
+            return dynamicToolFailure('read_file requires a non-empty path string.');
+        const target = await resolveWorkspaceToolPath(root, requestedPath);
+        const fileStat = await stat(target.path).catch((err) => {
+            throw new Error(`Cannot stat ${target.relativePath}: ${workflowToolErrorMessage(err)}`);
+        });
+        if (!fileStat.isFile())
+            return dynamicToolFailure(`${target.relativePath} is not a file.`);
+        if (fileStat.size > MAX_WORKSPACE_TOOL_READ_BYTES) {
+            return dynamicToolFailure(`${target.relativePath} is ${fileStat.size} bytes; limit is ${MAX_WORKSPACE_TOOL_READ_BYTES} bytes.`);
+        }
+        const text = await readFile(target.path, 'utf8').catch((err) => {
+            throw new Error(`Cannot read ${target.relativePath}: ${workflowToolErrorMessage(err)}`);
+        });
+        if (text.includes('\0'))
+            return dynamicToolFailure(`${target.relativePath} appears to be binary.`);
+        return dynamicToolSuccess([
+            `path: ${target.relativePath}`,
+            `bytes: ${Buffer.byteLength(text, 'utf8')}`,
+            '',
+            text,
+        ].join('\n'));
+    }
+    async listWorkspaceDirectory(root, args) {
+        const requestedPath = typeof args.path === 'string' && args.path.trim() ? args.path : '.';
+        const target = await resolveWorkspaceToolPath(root, requestedPath);
+        const entries = await readdir(target.path, { withFileTypes: true }).catch((err) => {
+            throw new Error(`Cannot list ${target.relativePath}: ${workflowToolErrorMessage(err)}`);
+        });
+        const sorted = entries
+            .map((entry) => `${entry.name}${entry.isDirectory() ? '/' : ''}`)
+            .sort((left, right) => left.localeCompare(right));
+        const visible = sorted.slice(0, MAX_WORKSPACE_TOOL_DIRECTORY_ENTRIES);
+        const truncated = sorted.length > visible.length
+            ? `\n... ${sorted.length - visible.length} more entries omitted`
+            : '';
+        return dynamicToolSuccess([
+            `path: ${target.relativePath}`,
+            `entries: ${sorted.length}`,
+            '',
+            ...visible,
+        ].join('\n') + truncated);
     }
     handleNotification(method, params) {
         const data = asRecord(params);
@@ -544,6 +675,42 @@ function readPath(value, path) {
     }
     return current;
 }
+async function resolveWorkspaceToolPath(root, requestedPath) {
+    const requested = requestedPath.trim();
+    const candidate = isAbsolute(requested) ? resolve(requested) : resolve(root, requested);
+    if (!pathInsideOrEqual(root, candidate)) {
+        throw new Error(`Path escapes workspace: ${requestedPath}`);
+    }
+    const canonicalPath = await realpath(candidate).catch((err) => {
+        throw new Error(`Path not found: ${requestedPath} (${workflowToolErrorMessage(err)})`);
+    });
+    if (!pathInsideOrEqual(root, canonicalPath)) {
+        throw new Error(`Path escapes workspace: ${requestedPath}`);
+    }
+    return {
+        path: canonicalPath,
+        relativePath: relative(root, canonicalPath) || '.',
+    };
+}
+function pathInsideOrEqual(parent, child) {
+    const candidate = relative(parent, child);
+    return candidate === '' || (!candidate.startsWith('..') && !isAbsolute(candidate));
+}
+function dynamicToolSuccess(text) {
+    return {
+        success: true,
+        contentItems: [{ type: 'inputText', text }],
+    };
+}
+function dynamicToolFailure(text) {
+    return {
+        success: false,
+        contentItems: [{ type: 'inputText', text }],
+    };
+}
+function workflowToolErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 export function usageFromCodexTokenUsage(value) {
     const usage = asRecord(value);
     const last = asRecord(usage?.last);

package/dist/runtime/workflow-runtime.d.ts

@@ -241,6 +241,7 @@ export declare class WorkflowTaskRegistry implements WorkflowRuntime {
     private runTask;
     private createVmGlobals;
     private runAgent;
+    private workspaceContext;
     private runAgentInner;
     private createAgentWorktree;
     private finalizeAgentWorktree;

package/dist/runtime/workflow-runtime.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { chmod, mkdir, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { promisify } from 'node:util';
@@ -12,6 +12,9 @@ const MAX_AGENT_CALLS = 1000;
 const MAX_PARALLELISM = 16;
 const DEFAULT_AGENT_STALL_TIMEOUT_MS = 180_000;
 const DEFAULT_AGENT_STALL_RETRY_LIMIT = 5;
+const DEFAULT_WORKSPACE_CONTEXT_MAX_FILES = 24;
+const DEFAULT_WORKSPACE_CONTEXT_MAX_FILE_BYTES = 12_000;
+const DEFAULT_WORKSPACE_CONTEXT_MAX_BYTES = 80_000;
 const execFileAsync = promisify(execFile);
 const PROJECT_WORKFLOW_DIRS = ['.codex/workflows'];
 const WORKFLOW_PERMISSION_REQUIRED_SOURCES = new Set(['script_path', 'project', 'user', 'plugin']);
@@ -54,6 +57,48 @@ const JSON_SCHEMA_KEYS = new Set([
     'title',
     'type',
 ]);
+const WORKSPACE_CONTEXT_EXCLUDED_DIRS = new Set([
+    '.git',
+    '.next',
+    '.turbo',
+    '.ultracode-for-codex',
+    'artifacts',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'out',
+]);
+const WORKSPACE_CONTEXT_ALLOWED_EXTENSIONS = new Set([
+    '.cjs',
+    '.css',
+    '.go',
+    '.html',
+    '.js',
+    '.json',
+    '.jsx',
+    '.md',
+    '.mjs',
+    '.py',
+    '.rs',
+    '.sh',
+    '.toml',
+    '.ts',
+    '.tsx',
+    '.txt',
+    '.yaml',
+    '.yml',
+]);
+const WORKSPACE_CONTEXT_PRIORITY_FILES = new Set([
+    'AGENTS.md',
+    'CONTRACT.md',
+    'IMPLEMENTATION_MAP.html',
+    'README.md',
+    'SKILL.md',
+    'ULTRACODE_INSTALL.md',
+    'package.json',
+    'tsconfig.json',
+]);
 const DEFAULT_BUILTIN_WORKFLOWS = [
     {
         name: 'code-review',
@@ -65,7 +110,14 @@ const input = args && typeof args === "object" ? args : {};
 const prompt = typeof input.prompt === "string" && input.prompt.trim()
   ? input.prompt
   : "Review the current repository for correctness risks.";
-return await agent(prompt, { label: "code-review" });`,
+const context = await workspaceContext({ query: prompt });
+return await agent([
+  prompt,
+  "",
+  "Use the deterministic workspace context below as primary evidence. Mention any missing evidence explicitly.",
+  "",
+  context
+].join("\\n"), { label: "code-review" });`,
     },
     {
         name: 'batch',
@@ -824,6 +876,9 @@ export class WorkflowTaskRegistry {
         host.pipeline = hardenCallable((items, ...stages) => {
             return this.trackWorkflowPromise(ctx, this.pipeline(ctx, items, stages));
         });
+        host.workspaceContext = hardenCallable((options) => {
+            return this.trackWorkflowPromise(ctx, this.workspaceContext(ctx, options));
+        });
         host.phase = hardenCallable((title) => this.phase(ctx, title));
         host.log = hardenCallable(log);
         host.consoleLog = hardenCallable((...values) => {
@@ -863,6 +918,12 @@ export class WorkflowTaskRegistry {
         operation.catch(() => undefined);
         return this.trackWorkflowPromise(ctx, operation);
     }
+    async workspaceContext(ctx, options) {
+        if (ctx.controller.signal.aborted || ctx.task.status !== 'running') {
+            throw workflowInputError('Workflow is aborted.');
+        }
+        return await buildWorkspaceContext(this.options.cwd ?? process.cwd(), normalizeWorkspaceContextOptions(options));
+    }
     async runAgentInner(ctx, prompt, options) {
         if (typeof prompt !== 'string' || prompt.trim() === '') {
             throw workflowInputError('agent(prompt) requires a non-empty string prompt.');
@@ -1482,6 +1543,198 @@ async function gitOutput(cwd, args) {
         throw new Error(message);
     }
 }
+async function buildWorkspaceContext(cwd, options) {
+    const root = await workspaceContextRoot(cwd);
+    const gitStatus = await gitOutput(root, ['status', '--short']).catch(() => '');
+    const explicitPaths = [
+        ...options.files,
+        ...extractMentionedWorkspacePaths(options.query ?? ''),
+    ];
+    const changedPaths = pathsFromGitStatus(gitStatus);
+    const listedPaths = await listWorkspaceContextCandidates(root);
+    const candidates = uniqueStrings([
+        ...explicitPaths,
+        ...changedPaths,
+        ...WORKSPACE_CONTEXT_PRIORITY_FILES,
+        ...listedPaths,
+    ]).filter(shouldIncludeWorkspaceContextPath);
+    const fileBlocks = [];
+    let usedBytes = 0;
+    for (const candidate of candidates) {
+        if (fileBlocks.length >= options.maxFiles)
+            break;
+        const block = await workspaceContextFileBlock(root, candidate, options.maxFileBytes).catch(() => null);
+        if (!block)
+            continue;
+        const blockBytes = Buffer.byteLength(block, 'utf8');
+        if (usedBytes + blockBytes > options.maxBytes) {
+            if (fileBlocks.length > 0)
+                break;
+            fileBlocks.push(block.slice(0, options.maxBytes));
+            break;
+        }
+        fileBlocks.push(block);
+        usedBytes += blockBytes;
+    }
+    return [
+        '## Workspace Context',
+        `Root: ${root}`,
+        '',
+        '### Git Status',
+        gitStatus.trim() ? gitStatus : '(clean or unavailable)',
+        '',
+        '### Included Files',
+        fileBlocks.length ? fileBlocks.join('\n\n') : '(no readable text files selected)',
+    ].join('\n');
+}
+function normalizeWorkspaceContextOptions(value) {
+    const options = asRecord(value) ?? {};
+    const query = typeof options.query === 'string' ? options.query : undefined;
+    const files = Array.isArray(options.files)
+        ? options.files.filter((item) => typeof item === 'string' && item.trim() !== '')
+        : [];
+    return {
+        ...(query ? { query } : {}),
+        files,
+        maxFiles: boundedPositiveInteger(options.maxFiles, DEFAULT_WORKSPACE_CONTEXT_MAX_FILES, 1, 100),
+        maxFileBytes: boundedPositiveInteger(options.maxFileBytes, DEFAULT_WORKSPACE_CONTEXT_MAX_FILE_BYTES, 1_000, 50_000),
+        maxBytes: boundedPositiveInteger(options.maxBytes, DEFAULT_WORKSPACE_CONTEXT_MAX_BYTES, 10_000, 200_000),
+    };
+}
+function boundedPositiveInteger(value, fallback, min, max) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    return Math.max(min, Math.min(max, Math.floor(value)));
+}
+async function workspaceContextRoot(cwd) {
+    try {
+        return await gitOutput(cwd, ['rev-parse', '--show-toplevel']);
+    }
+    catch {
+        return await realpath(cwd).catch(() => resolve(cwd));
+    }
+}
+async function listWorkspaceContextCandidates(root) {
+    try {
+        return splitLines(await gitOutput(root, ['ls-files', '--cached', '--others', '--exclude-standard']));
+    }
+    catch {
+        return await walkWorkspaceContextFiles(root);
+    }
+}
+async function walkWorkspaceContextFiles(root) {
+    const found = [];
+    async function walk(dir) {
+        if (found.length >= 500)
+            return;
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (found.length >= 500)
+                return;
+            if (WORKSPACE_CONTEXT_EXCLUDED_DIRS.has(entry.name))
+                continue;
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (entry.isFile())
+                found.push(relative(root, fullPath));
+        }
+    }
+    await walk(root);
+    return found;
+}
+function extractMentionedWorkspacePaths(query) {
+    const out = new Set();
+    for (const file of WORKSPACE_CONTEXT_PRIORITY_FILES) {
+        if (query.includes(file))
+            out.add(file);
+    }
+    const matches = query.match(/[A-Za-z0-9_.@+-]+(?:\/[A-Za-z0-9_.@+-]+)+(?:\.[A-Za-z0-9]+)?(?::\d+)?/g) ?? [];
+    for (const match of matches) {
+        if (match.includes('://'))
+            continue;
+        out.add(match.replace(/:\d+$/, ''));
+    }
+    return [...out];
+}
+function pathsFromGitStatus(status) {
+    const paths = [];
+    for (const line of status.split(/\r?\n/).filter(Boolean)) {
+        const rawPath = line.length > 3 ? line.slice(3).trim() : line.trim();
+        if (!rawPath)
+            continue;
+        const path = rawPath.includes(' -> ') ? rawPath.split(' -> ').at(-1) ?? rawPath : rawPath;
+        paths.push(path.replace(/^"|"$/g, ''));
+    }
+    return paths;
+}
+async function workspaceContextFileBlock(root, requestedPath, maxFileBytes) {
+    const resolved = await resolveWorkspaceContextPath(root, requestedPath);
+    if (!resolved)
+        return null;
+    const fileStat = await stat(resolved.path).catch(() => null);
+    if (!fileStat?.isFile() || fileStat.size > maxFileBytes)
+        return null;
+    const text = await readFile(resolved.path, 'utf8').catch(() => null);
+    if (text === null || text.includes('\0'))
+        return null;
+    return [
+        `--- ${resolved.relativePath} (${fileStat.size} bytes) ---`,
+        numberWorkspaceContextLines(text),
+    ].join('\n');
+}
+async function resolveWorkspaceContextPath(root, requestedPath) {
+    const requested = requestedPath.trim();
+    if (!requested)
+        return null;
+    const candidate = isAbsolute(requested) ? resolve(requested) : resolve(root, requested);
+    if (!pathInsideOrEqual(root, candidate))
+        return null;
+    const canonical = await realpath(candidate).catch(() => null);
+    if (!canonical || !pathInsideOrEqual(root, canonical))
+        return null;
+    return {
+        path: canonical,
+        relativePath: relative(root, canonical) || '.',
+    };
+}
+function shouldIncludeWorkspaceContextPath(path) {
+    const normalized = path.replaceAll('\\', '/').replace(/^\.\/+/, '');
+    if (!normalized || normalized.startsWith('../') || normalized.includes('/../'))
+        return false;
+    const parts = normalized.split('/');
+    if (parts.some((part) => WORKSPACE_CONTEXT_EXCLUDED_DIRS.has(part)))
+        return false;
+    const name = parts.at(-1) ?? '';
+    if (WORKSPACE_CONTEXT_PRIORITY_FILES.has(name))
+        return true;
+    const dot = name.lastIndexOf('.');
+    if (dot < 0)
+        return false;
+    return WORKSPACE_CONTEXT_ALLOWED_EXTENSIONS.has(name.slice(dot).toLowerCase());
+}
+function numberWorkspaceContextLines(text) {
+    return text.split(/\r?\n/).map((line, index) => {
+        return `${String(index + 1).padStart(4, ' ')} | ${line}`;
+    }).join('\n');
+}
+function splitLines(value) {
+    return value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const normalized = value.trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
 async function removeCleanGitWorktree(worktree) {
     try {
         await gitOutput(worktree.gitRoot, ['worktree', 'remove', '--force', worktree.path]);
@@ -2507,6 +2760,7 @@ function installWorkflowVmGlobals(context, globals) {
         '  define(globalThis, "agent", { value: (...values) => __host.agent(...values), writable: false, configurable: false });',
         '  define(globalThis, "parallel", { value: (...values) => __host.parallel(...values), writable: false, configurable: false });',
         '  define(globalThis, "pipeline", { value: (...values) => __host.pipeline(...values), writable: false, configurable: false });',
+        '  define(globalThis, "workspaceContext", { value: (...values) => __host.workspaceContext(...values), writable: false, configurable: false });',
         '  define(globalThis, "phase", { value: (...values) => __host.phase(...values), writable: false, configurable: false });',
         '  define(globalThis, "log", { value: (...values) => __host.log(...values), writable: false, configurable: false });',
         '  define(globalThis, "workflow", { value: (...values) => __host.workflow(...values), writable: false, configurable: false });',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",

package/skills/ultracode-for-codex/SKILL.md

@@ -35,7 +35,7 @@ For source-checkout validation before publish:
 
 ```bash
 npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-0.2.0.tgz
+npm install --save-dev ./artifacts/ultracode-for-codex-0.2.1.tgz
 ```
 
 CLI behavior:
@@ -58,6 +58,10 @@ CLI behavior:
 
 - Use Codex app-server over stdio as the production backend.
 - Keep direct provider credentials out of Codex child process environments.
+- Codex subagents run against the requested workflow cwd and have bounded
+  read-only workspace tools for text file reads and directory listings.
+- Built-in `code-review` injects deterministic workspace context and prioritizes
+  files explicitly mentioned in the prompt.
 - Keep workflow execution local and command-owned; settings default to OS
   background execution and `--execution attached` keeps the process connected
   until completion.