ultracode-for-codex 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,158 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work by
+the copyright owner or by an individual or Legal Entity authorized to submit on
+behalf of the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent to the
+Licensor or its representatives, including but not limited to communication on
+electronic mailing lists, source code control systems, and issue tracking
+systems that are managed by, or on behalf of, the Licensor for the purpose of
+discussing and improving the Work, but excluding communication that is
+conspicuously marked or otherwise designated in writing by the copyright owner
+as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the Derivative
+Works; within the Source form or documentation, if provided along with the
+Derivative Works; or, within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents of the NOTICE
+file are for informational purposes only and do not modify the License. You may
+add Your own attribution notices within Derivative Works that You distribute,
+alongside or as an addendum to the NOTICE text from the Work, provided that such
+additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied, including, without
+limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
+MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+responsible for determining the appropriateness of using or redistributing the
+Work and assume any risks associated with Your exercise of permissions under
+this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations or
+rights consistent with this License. However, in accepting such obligations, You
+may act only on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify, defend, and hold
+each Contributor harmless for any liability incurred by, or claims asserted
+against, such Contributor by reason of your accepting any such warranty or
+additional liability.
+
+END OF TERMS AND CONDITIONS

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.2.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.2.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/docs/provenance-audit.md

@@ -0,0 +1,56 @@
+# Provenance Audit
+
+Date: 2026-06-22
+
+## Scope
+
+This audit checked:
+
+- tracked repository files;
+- generated npm package contents for `ultracode-for-codex@0.2.2`;
+- the locally installed companion Codex skill.
+
+Generated build output and package tarballs were checked as projections of the
+tracked source. Dependency source trees were treated as third-party dependency
+inputs, not project-authored code.
+
+## Result
+
+Repository and package artifacts are clear for the Apache-2.0 license from an
+artifact-provenance perspective.
+
+License transition completed:
+
+- Apache-2.0 `LICENSE` file is present;
+- `package.json` and `package-lock.json` declare `Apache-2.0`;
+- package version is prepared as `0.2.2` for the license-bearing patch release.
+
+## Evidence
+
+- High-risk historical-source marker search: zero matches in tracked source,
+  generated package contents, and local companion skill after cleanup.
+- Legacy API-project marker search: zero matches in tracked source, generated
+  package contents, and local companion skill after cleanup.
+- Packaged runtime contents are limited to the CLI runtime, current docs,
+  settings, and companion skill.
+- Production dependencies: none.
+- Development dependencies: TypeScript and Node type packages only.
+- Bundled third-party code: none.
+
+Expected platform-control markers remain:
+
+- provider environment variable names used by child-process environment
+  stripping and tests;
+- Codex feature names used to disable unrelated child runtime features;
+- npm registry and GitHub metadata URLs.
+
+## Remediation Completed
+
+The local companion skill had stale local-only reference files that were not in
+the package skill. Those local references were removed, and the local skill agent
+metadata was synchronized with the packaged skill.
+
+## Residual Risk
+
+This audit validates repository and package artifacts. It does not determine
+external service contract compliance or replace legal review.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
   "keywords": [
     "codex",
@@ -17,7 +17,7 @@
     "type": "git",
     "url": "git+https://github.com/kangminlee-maker/ultracode-for-codex.git"
   },
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "type": "module",
   "bin": {
     "ultracode-for-codex": "dist/cli.js"
@@ -41,6 +41,7 @@
     "skills/ultracode-for-codex/",
     "settings.json",
     "README.md",
+    "docs/provenance-audit.md",
     "docs/ultracode-p3a-journal-design.md",
     "docs/ultracode-p3b-resume-cache.md",
     "docs/ultracode-p3c-worktree-isolation.md"
@@ -61,7 +62,6 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "run": "npm run build && node dist/cli.js run --accept-llm-guide=v1"
   },
-  "dependencies": {},
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.9.3"

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.2.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.