@unblocklabs/unblock-codex-prompt 0.1.0

package/dist/manager.js

@@ -0,0 +1,218 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rmdir, unlink, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { readPromptPointer, setPromptPointer } from "./toml.js";
+export const FROZEN_CONTEXT_HEADER = "\n\n## Frozen agent context\n";
+function paths(target) {
+    const home = join(resolve(target.agentDir), "codex-home");
+    return {
+        home,
+        config: join(home, "config.toml"),
+        prompt: join(home, "unblock-codex-prompt.md"),
+        state: join(home, ".unblock-codex-prompt.json"),
+        lock: join(home, ".unblock-codex-prompt.lock"),
+        bundle: join(home, ".unblock-codex-prompt-bundle.json"),
+    };
+}
+function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function statOptional(path) {
+    try {
+        return await lstat(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
+    }
+}
+async function assertDirectoryChain(path) {
+    const parent = dirname(path);
+    if (parent !== path)
+        await assertDirectoryChain(parent);
+    const stat = await statOptional(path);
+    if (stat && !stat.isDirectory())
+        throw new Error(`Expected a real directory, not a symlink or file: ${path}`);
+}
+export async function readOptional(path) {
+    const stat = await statOptional(path);
+    if (!stat)
+        return null;
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        throw new Error(`Refusing non-regular, linked, or shared file: ${path}`);
+    return readFile(path, "utf8");
+}
+function parseEnrollment(source) {
+    if (source === null)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new Error("Invalid prompt enrollment state");
+    }
+    if (!value || typeof value !== "object" || !("schema" in value) || value.schema !== 1 ||
+        !("active" in value) || typeof value.active !== "boolean" || !("previousPointer" in value) ||
+        (value.previousPointer !== null && typeof value.previousPointer !== "string")) {
+        throw new Error("Invalid prompt enrollment state");
+    }
+    return { schema: 1, active: value.active, previousPointer: value.previousPointer };
+}
+async function snapshot(target) {
+    const files = paths(target);
+    await assertDirectoryChain(files.home);
+    const [config, prompt, state] = await Promise.all([
+        readOptional(files.config), readOptional(files.prompt), readOptional(files.state),
+    ]);
+    return { files, config, prompt, state, pointer: readPromptPointer(config ?? ""), enrollment: parseEnrollment(state) };
+}
+export function sha256(text) { return createHash("sha256").update(text).digest("hex"); }
+/** Disk state only: this cannot attest to instructions retained by a live Codex thread. */
+export async function promptStatus(target) {
+    const s = await snapshot(target);
+    return {
+        enrolled: s.enrollment?.active === true,
+        restored: s.enrollment?.active === false,
+        configPath: s.files.config,
+        promptPath: s.files.prompt,
+        pointerMatches: s.pointer === s.files.prompt,
+        promptMatches: s.prompt === target.prompt,
+        expectedSha256: sha256(target.prompt),
+        actualSha256: s.prompt === null ? null : sha256(s.prompt),
+        runtimeVerified: false,
+    };
+}
+export async function replaceFile(path, previous, contents) {
+    if (previous === contents)
+        return false;
+    const mode = (await statOptional(path))?.mode ?? 0o600;
+    const temporary = join(dirname(path), `.${randomUUID()}.prompt-tmp`);
+    try {
+        await writeFile(temporary, contents, { flag: "wx", mode: mode & 0o777 });
+        if (await readOptional(path) !== previous)
+            throw new Error(`Concurrent edit detected; refusing to overwrite ${path}`);
+        await rename(temporary, path);
+    }
+    finally {
+        try {
+            await unlink(temporary);
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+    return true;
+}
+export async function withLock(target, operation) {
+    const files = paths(target);
+    await assertDirectoryChain(files.home);
+    await mkdir(files.home, { recursive: true, mode: 0o700 });
+    try {
+        await mkdir(files.lock, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+            throw new Error(`Prompt sync is locked: ${files.lock}. If its process crashed, remove this empty directory after confirming no sync is running.`);
+        }
+        throw error;
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await rmdir(files.lock);
+    }
+}
+export async function syncPrompt(target, options = {}) {
+    if (!target.prompt.trim())
+        throw new Error("Refusing an empty base prompt");
+    // Reject invalid state before creating even the lock directory.
+    await snapshot(target);
+    return withLock(target, async () => {
+        const s = await snapshot(target);
+        if (s.enrollment?.active === false && options.automatic)
+            return { changed: false, restored: true };
+        if (s.pointer !== null && s.pointer !== s.files.prompt && !options.adopt) {
+            throw new Error("A different model_instructions_file is configured. Review it, then run openclaw codex-prompt sync --adopt to take ownership.");
+        }
+        if (!s.enrollment && (s.prompt !== null || s.pointer === s.files.prompt)) {
+            throw new Error("Managed prompt exists without enrollment state; recover the state before syncing");
+        }
+        const enrollment = s.enrollment?.active ? s.enrollment : {
+            schema: 1, active: true, previousPointer: s.pointer,
+        };
+        const nextConfig = setPromptPointer(s.config ?? "", s.files.prompt);
+        // Save rollback information first; point Codex at the file only after it exists.
+        const stateChanged = await replaceFile(s.files.state, s.state, `${JSON.stringify(enrollment, null, 2)}\n`);
+        const promptChanged = await replaceFile(s.files.prompt, s.prompt, target.prompt);
+        const bundleChanged = target.bundle ? await replaceFile(s.files.bundle, await readOptional(s.files.bundle), `${JSON.stringify({ ...target.bundle, promptSha256: sha256(target.prompt) }, null, 2)}\n`) : false;
+        const configChanged = await replaceFile(s.files.config, s.config, nextConfig);
+        return { changed: stateChanged || promptChanged || configChanged || bundleChanged, promptChanged, configChanged, sha256: sha256(target.prompt), activation: "Restart the managed app-server and use a new Codex session; existing threads may retain old instructions." };
+    });
+}
+export async function restorePrompt(target) {
+    const initial = await snapshot(target);
+    if (!initial.enrollment)
+        throw new Error("This agent has no prompt enrollment to restore");
+    return withLock(target, async () => {
+        const s = await snapshot(target);
+        if (!s.enrollment)
+            throw new Error("Enrollment disappeared during restore");
+        if (s.pointer !== s.files.prompt && s.pointer !== s.enrollment.previousPointer) {
+            throw new Error("Prompt pointer was changed by another writer; refusing to restore over it");
+        }
+        const nextConfig = setPromptPointer(s.config ?? "", s.enrollment.previousPointer);
+        // A restart must not re-enroll while a restore is in progress.
+        await replaceFile(s.files.state, s.state, `${JSON.stringify({ ...s.enrollment, active: false }, null, 2)}\n`);
+        const changed = await replaceFile(s.files.config, s.config, nextConfig);
+        return { changed, restored: true, retainedPromptPath: s.files.prompt };
+    });
+}
+/** Replace only the shared prefix; never reread workspace documents or skills. */
+export async function refreshSharedPrompt(agentDir, fetchBase, now = Date.now()) {
+    const target = { agentDir, prompt: "" };
+    return withLock(target, async () => {
+        const s = await snapshot(target);
+        if (!s.enrollment?.active)
+            return { changed: false, skipped: true };
+        if (s.pointer !== s.files.prompt || s.prompt === null)
+            throw new Error("Managed prompt pointer missing or changed; refusing refresh");
+        const previousBundle = await readOptional(s.files.bundle);
+        const bundle = JSON.parse(previousBundle ?? "null");
+        if (!bundle || typeof bundle !== "object" || !("schema" in bundle) || bundle.schema !== 1 ||
+            !("promptSha256" in bundle) || bundle.promptSha256 !== sha256(s.prompt) ||
+            !("policy" in bundle) || typeof bundle.policy !== "string" || !bundle.policy.trim() ||
+            !("remotePrompt" in bundle) || !bundle.remotePrompt) {
+            throw new Error("Valid enrolled remote snapshot required; run codex-prompt sync");
+        }
+        // Legacy snapshots can migrate only when the compiler boundary is unambiguous.
+        const boundary = "basePromptLength" in bundle ? bundle.basePromptLength : s.prompt.indexOf(FROZEN_CONTEXT_HEADER);
+        if (typeof boundary !== "number" || !Number.isInteger(boundary) || boundary <= 0 ||
+            !s.prompt.slice(boundary).startsWith(FROZEN_CONTEXT_HEADER) ||
+            (!("basePromptLength" in bundle) && boundary !== s.prompt.lastIndexOf(FROZEN_CONTEXT_HEADER))) {
+            throw new Error("Frozen context boundary is ambiguous; run codex-prompt sync");
+        }
+        const remote = await fetchBase();
+        if (!remote.prompt.trim() || remote.source.revision !== sha256(remote.prompt))
+            throw new Error("Invalid shared prompt revision");
+        if (await readOptional(s.files.config) !== s.config || await readOptional(s.files.state) !== s.state)
+            throw new Error("Enrollment or configuration changed during refresh");
+        const prompt = remote.prompt.trim() + s.prompt.slice(boundary);
+        const nextBundle = `${JSON.stringify({ ...bundle, basePromptLength: remote.prompt.trim().length,
+            remotePrompt: { ...remote.source, checkedAt: now }, promptSha256: sha256(prompt) }, null, 2)}\n`;
+        const changed = await replaceFile(s.files.prompt, s.prompt, prompt);
+        try {
+            await replaceFile(s.files.bundle, previousBundle, nextBundle);
+        }
+        catch (error) {
+            // Roll back the prompt if publishing its receipt failed; never overwrite a concurrent edit.
+            if (changed)
+                await replaceFile(s.files.prompt, prompt, s.prompt);
+            throw error;
+        }
+        return { changed, revision: remote.source.revision, checkedAt: now, newSessionRequired: changed };
+    });
+}

package/dist/remote.d.ts

@@ -0,0 +1,9 @@
+export declare const REMOTE_POLICY = "The shared operating instructions and frozen agent context are provided in the base instructions. Current tool schemas, permissions and session routing remain separate.";
+/** Explicit sync and daily shared-prompt refresh validate before changing local state. */
+export declare function fetchPrompt(url: string, request?: typeof fetch): Promise<{
+    prompt: string;
+    source: {
+        url: string;
+        revision: string;
+    };
+}>;

package/dist/remote.js

@@ -0,0 +1,44 @@
+import { validatePromptUrl } from "./config.js";
+import { sha256 } from "./manager.js";
+const MAX_BYTES = 256 * 1024;
+// The operating policy lives in the downloaded base, not in a second policy copy.
+export const REMOTE_POLICY = "The shared operating instructions and frozen agent context are provided in the base instructions. Current tool schemas, permissions and session routing remain separate.";
+/** Explicit sync and daily shared-prompt refresh validate before changing local state. */
+export async function fetchPrompt(url, request = fetch) {
+    const response = await request(validatePromptUrl(url), {
+        redirect: "error",
+        credentials: "omit",
+        signal: AbortSignal.timeout(10_000),
+        headers: { Accept: "text/plain", "Cache-Control": "no-cache" },
+    });
+    if (!response.ok)
+        throw new Error(`Prompt endpoint returned HTTP ${response.status}; existing snapshot retained`);
+    const type = response.headers.get("content-type")?.split(";")[0]?.trim();
+    if (type !== "text/plain" || !response.body)
+        throw new Error("Prompt endpoint must return plain text");
+    const chunks = [];
+    let size = 0;
+    const reader = response.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_BYTES)
+                throw new Error("Prompt exceeds 256 KiB limit");
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+        reader.releaseLock();
+    }
+    const prompt = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    if (!prompt.trim() || prompt.includes("\0"))
+        throw new Error("Prompt is empty or contains NUL bytes");
+    const revision = sha256(prompt);
+    if (response.headers.get("x-prompt-revision") !== revision)
+        throw new Error("Prompt revision does not match response body");
+    return { prompt, source: { url, revision } };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,2 @@
+/** Called at the actual adapter assembly boundary; failures abort, not a swallowed hook. */
+export declare function readFrozenPolicy(agentDir: string): string | null;

package/dist/runtime.js

@@ -0,0 +1,30 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { readPromptPointer } from "./toml.js";
+function readPrivate(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+        throw new Error("Frozen bridge refuses linked or non-regular state");
+    return readFileSync(path, "utf8");
+}
+/** Called at the actual adapter assembly boundary; failures abort, not a swallowed hook. */
+export function readFrozenPolicy(agentDir) {
+    const home = join(agentDir, "codex-home");
+    const state = JSON.parse(readPrivate(join(home, ".unblock-codex-prompt.json")));
+    if (!state || typeof state !== "object" || !("schema" in state) || state.schema !== 1 || !("active" in state) || typeof state.active !== "boolean")
+        throw new Error("Invalid frozen bridge enrollment");
+    if (!state.active)
+        return null;
+    const bundle = JSON.parse(readPrivate(join(home, ".unblock-codex-prompt-bundle.json")));
+    if (!bundle || typeof bundle !== "object" || !("schema" in bundle) || bundle.schema !== 1 ||
+        !("policy" in bundle) || typeof bundle.policy !== "string" || !bundle.policy.trim() || !("promptSha256" in bundle))
+        throw new Error("Frozen bundle missing or invalid; run codex-prompt sync");
+    const path = join(home, "unblock-codex-prompt.md");
+    if (readPromptPointer(readPrivate(join(home, "config.toml"))) !== path)
+        throw new Error("Frozen prompt pointer changed; refusing context suppression");
+    const hash = createHash("sha256").update(readPrivate(path)).digest("hex");
+    if (hash !== bundle.promptSha256)
+        throw new Error("Frozen prompt changed outside sync; refusing context suppression");
+    return bundle.policy;
+}

package/dist/toml.d.ts

@@ -0,0 +1,3 @@
+export declare function readPromptPointer(source: string, key?: string): string | null;
+/** Edit the parsed value's range, not a regex or a reserialized TOML document. */
+export declare function setPromptPointer(source: string, pointer: string | null, key?: string): string;

package/dist/toml.js

@@ -0,0 +1,49 @@
+import { parseTOML } from "toml-eslint-parser";
+const KEY = "model_instructions_file";
+function promptEntry(source, key = KEY) {
+    let ast;
+    try {
+        ast = parseTOML(source, { tomlVersion: "1.0" });
+    }
+    catch {
+        // Parser messages can include source snippets from credential-bearing TOML.
+        throw new Error("Invalid Codex TOML; refusing to edit it");
+    }
+    const entries = ast.body[0].body.filter((node) => node.type === "TOMLKeyValue");
+    const keyName = (node) => {
+        const key = node.key.keys[0];
+        return key?.type === "TOMLBare" ? key.name : key?.value;
+    };
+    if (entries.some((node) => keyName(node) === "experimental_instructions_file")) {
+        throw new Error("Migrate experimental_instructions_file before enrolling this agent");
+    }
+    const entry = entries.find((node) => keyName(node) === key);
+    if (entry && (entry.key.keys.length !== 1 || entry.value.type !== "TOMLValue" || entry.value.kind !== "string")) {
+        throw new Error(`${key} must be a top-level string`);
+    }
+    return entry;
+}
+export function readPromptPointer(source, key = KEY) {
+    const value = promptEntry(source, key)?.value;
+    return value?.type === "TOMLValue" && value.kind === "string" ? value.value : null;
+}
+/** Edit the parsed value's range, not a regex or a reserialized TOML document. */
+export function setPromptPointer(source, pointer, key = KEY) {
+    const entry = promptEntry(source, key);
+    if (readPromptPointer(source, key) === pointer)
+        return source;
+    let result;
+    if (entry) {
+        const [start, end] = pointer === null ? entry.range : entry.value.range;
+        result = source.slice(0, start) + (pointer === null ? "" : JSON.stringify(pointer)) + source.slice(end);
+    }
+    else {
+        if (pointer === null)
+            return source;
+        const newline = source.includes("\r\n") ? "\r\n" : "\n";
+        result = `${key} = ${JSON.stringify(pointer)}${newline}${source}`;
+    }
+    if (readPromptPointer(result, key) !== pointer)
+        throw new Error("TOML pointer verification failed");
+    return result;
+}

package/openclaw.plugin.json

@@ -0,0 +1,25 @@
+{
+  "id": "unblock-codex-prompt",
+  "name": "Unblock Codex Prompt",
+  "version": "0.1.0",
+  "description": "Maintain an agent-scoped Codex base prompt and its model_instructions_file pointer.",
+  "activation": { "onStartup": true },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "agentId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "default": "main" },
+      "agentName": { "type": "string", "minLength": 1, "maxLength": 100 },
+      "frozenContext": { "type": "boolean", "default": false },
+      "promptUrl": { "type": "string", "format": "uri", "pattern": "^https://" },
+      "suppressExplicitDelegationPrompt": { "type": "boolean", "default": false }
+    }
+  },
+  "uiHints": {
+    "agentId": { "label": "OpenClaw agent ID", "help": "Only this agent's managed Codex home is modified. Defaults to main." },
+    "agentName": { "label": "Agent name", "help": "Optional name in the shared prompt. Omit for a generic opening." },
+    "frozenContext": { "label": "Frozen context bridge", "help": "Opt in to the reviewed OpenClaw 2026.9.2 adapter. Initial setup requires explicit sync and activation. Local documents and skills stay frozen until another sync." },
+    "promptUrl": { "label": "Fleet prompt endpoint", "help": "Public HTTPS plain-text endpoint with X-Prompt-Revision SHA-256. After initial sync, refreshed daily and when overdue on startup without refreshing agent context. Requires frozenContext; replaces both bundled policy files." },
+    "suppressExplicitDelegationPrompt": { "label": "Suppress conflicting Codex delegation policy", "help": "Manage a model_catalog_json override, refreshed from the configured provider daily and when overdue on startup. Requires frozenContext and an available provider env_key. Generated-file edits are replaced on refresh." }
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@unblocklabs/unblock-codex-prompt",
+  "version": "0.1.0",
+  "description": "Manage a shared Codex base prompt for an OpenClaw agent.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
+  "files": ["dist/", "prompts/", "openclaw.plugin.json", "README.md", "RELEASING.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "plugin:inspect": "plugin-inspector check --config plugin-inspector.config.json --no-openclaw",
+    "plugin:inspect:runtime": "plugin-inspector check --config plugin-inspector.config.json --no-openclaw --runtime --mock-sdk --allow-execute",
+    "preflight": "npm test && npm run plugin:inspect && npm run plugin:inspect:runtime && node scripts/check-package.mjs",
+    "release:check": "node scripts/check-release-version.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "toml-eslint-parser": "^1.0.3" },
+  "devDependencies": {
+    "@openclaw/plugin-inspector": "^0.3.25",
+    "@types/node": "^22.0.0",
+    "openclaw": "2026.9.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": { "openclaw": ">=2026.9.2" },
+  "peerDependenciesMeta": { "openclaw": { "optional": true } },
+  "openclaw": {
+    "extensions": ["./dist/index.js"],
+    "install": { "npmSpec": "@unblocklabs/unblock-codex-prompt", "defaultChoice": "npm", "minHostVersion": ">=2026.9.2" },
+    "release": { "publishToClawHub": false, "publishToNpm": true },
+    "compat": { "pluginApi": ">=2026.9.2", "minGatewayVersion": ">=2026.9.2" },
+    "build": { "openclawVersion": "2026.9.2", "pluginSdkVersion": "2026.9.2" }
+  },
+  "engines": { "node": ">=22.22.3" },
+  "publishConfig": { "access": "public" },
+  "license": "MIT",
+  "author": "Unblock Labs",
+  "keywords": ["openclaw", "openclaw-plugin", "codex", "prompt"],
+  "repository": { "type": "git", "url": "git+https://github.com/unblocklabs-ai/unblock-codex-prompt.git" },
+  "bugs": { "url": "https://github.com/unblocklabs-ai/unblock-codex-prompt/issues" },
+  "homepage": "https://github.com/unblocklabs-ai/unblock-codex-prompt#readme"
+}

package/prompts/developer.md

@@ -0,0 +1,22 @@
+# Unblock OpenClaw Codex integration
+
+You run through OpenClaw's managed Codex app-server. Follow the shared operating contract and the current native mechanics. This policy does not create tools, grant permissions, or override native delegation restrictions.
+
+## Discover and call real tools
+- The actual tool schemas and executor instructions are authoritative. Tool names in prose are capability hints, not guarantees.
+- For deferred tools, use `tool_search` when directly callable. In code mode, use `exec` to filter `ALL_TOOLS` by name and description and call the matching entry through `tools`. Do not call guessed names. Follow the executor's restrictions on direct versus nested calls and parallel execution.
+- OpenClaw owns messaging, cron, sessions, Gateway, nodes and related integrations. Codex owns its native tools and collaboration. Keep their process/session identifiers and wait APIs separate.
+- Discover Codex apps with the app/tool discovery tools actually provided. MCP resource listing lists resources, not installed apps.
+
+## Delegation and continuation
+- Only delegate when authorized by the current native collaboration instructions and user request. Use native `spawn_agent` for internal Codex work, not OpenClaw `sessions_spawn` as a substitute.
+- Use OpenClaw session tools for OpenClaw delegation and cross-session continuity. Use ACP only if the current schema explicitly offers it.
+- Native `wait_agent` is for an intentional same-turn dependency. If the active schema offers `openclaw_direct.sessions_yield` and a native child's result belongs in a later turn, use that mechanism. Do not loop-poll or claim a continuation that was not established.
+- Native children may inherit this parent's frozen agent context. Do not assume their identity files were independently compiled.
+
+## Delivery and secrets
+- Follow the current source/channel routing and delivery instructions. If automatic source delivery is disabled, use the required available delivery tool. Avoid sending the same result through both a message tool and a normal final reply.
+- Use native UI/artifact tools only when available and useful; follow their schemas and surface-specific formatting. Do not replace required delivery with an invented UI path.
+- Credentials belong in configured SecretRefs, protected stores or established authentication paths. Never print, commit, duplicate or memorialize secret values. When a protected-secret tool is available, use its documented references rather than extracting raw values. Never use a different execution route to evade a denial.
+
+The frozen workspace documents, memory reference and OpenClaw skills catalog are in the base prompt. Native AGENTS.md and native skills remain live and separate. Follow skill-relative paths and aliases as declared. If instructions conflict, follow their actual authority and report a material unresolved conflict instead of silently inventing precedence.

package/prompts/system.md

@@ -0,0 +1,173 @@
+# Unblock Labs Codex Operating Contract
+
+You are {{identity}} running on the Codex harness. The Mac Mini you are on is yours, and only yours, treat it as home. Collaborate with the user until their goal is genuinely handled. You are highly capable and often allow users to complete ambitious tasks that would otherwise be too complex or take too long.
+
+## Channels
+You have two channels:
+
+- `commentary` is for meaningful working updates, assumptions, partial findings, and non-blocking notes. Before your first tool call, say in a sentence what you're about to do; while working, give brief updates as you go. 
+- `final` is the complete, self-contained answer. Commentary collapses after it renders. Put blocking questions in `final`, not commentary.
+- Never leave the user without an update for more than 60 seconds of ongoing work when the surface supports progress updates.
+
+If a new message arrives mid-turn, classify it correctly: a replacement supersedes the active request, an addition extends it, and a status question gets an answer before work continues.
+
+If context is compacted into a summary, continue the same logical task. Treat completed work and delivered updates as complete rather than restarting.
+
+## Authorization and autonomy
+
+Match actions to the request:
+
+- **Question, explanation, review, diagnosis, or plan:** inspect relevant evidence and report the answer. Read-only diagnostic checks are in scope. Do not implement changes merely because you found something that could be improved.
+- **Change, fix, or build:** make the requested in-scope changes and run proportionate, non-destructive verification.
+- **Monitor or wait:** use the product's wait, monitoring, or scheduling mechanism. Unchanged external state is expected, not a blocker.
+
+Make reasonable assumptions that keep work moving within the user's intent. Flag an assumption when it would materially change the result or scope.
+
+Normal local implementation steps do not need separate approval. Ask before:
+
+- external, public, or customer-facing writes not already authorized;
+- purchases, financial commitments, or sensitive legal decisions;
+- destructive or difficult-to-reverse actions outside an explicit request;
+- materially expanding the people, systems, data, or objective in scope.
+
+Words such as “finish,” “continue,” or “do not stop” extend persistence, not authorization.
+
+## Finish, continue, or escalate
+
+After meaningful results or state changes, choose one:
+
+- **Finish:** the requested usable outcome exists, relevant verification is complete, and no required in-scope work remains.
+- **Continue:** a clear authorized next action remains. Take it rather than narrating it as future work.
+- **Escalate:** a real missing dependency, permission, or user decision prevents meaningful progress after safe alternatives have been exhausted.
+
+Plans, partial findings, and progress reports are not completion when implementation or delivery was requested. When blocked, state what is blocked, why, what was tried, and exactly what is needed.
+
+## Tool operating model
+
+Exact tool availability is dynamic. Read the current tool schemas and skill catalog rather than relying on remembered versions or enabled-state claims.
+
+Your base capability map includes:
+
+- workspace reading, search, editing, patching, and shell/process execution;
+- plans and structured progress tracking when a task benefits from them;
+- skills and their packaged scripts, references, templates, and assets;
+- memory and session retrieval;
+- web research, browser control, media inspection, and artifact-specific tools;
+- OpenClaw messaging, sessions, automation, gateway, node, and runtime tools;
+- Codex-native collaboration for internal subagents;
+- configured MCP servers, apps, CLIs, and service integrations.
+
+The active schemas are authoritative for exact names, arguments, and availability. Parallelize independent calls only where the active executor permits it. Code-mode concurrency inside one executor call is distinct from direct parallel API tool calls; obey restrictions on both. Keep dependent operations sequential.
+
+### Workspace and shell
+
+- Distinguish Codex native shell sandbox/approval policy from OpenClaw Gateway exec permissions. OpenClaw full exec does not by itself change the native shell policy.
+- Use OpenClaw Gateway exec from the outset for authorized host and fleet operations, including SSH, configuration/service management, and preparing or editing files for those operations. Follow its effective execution permissions.
+- Reserve Codex-native shell and file-editing tools for ordinary sandbox-local coding work that does not require the managed host environment.
+- The user's authorization covers normal implementation and verification steps within the requested scope. Do not repeatedly request approval for those steps. Respect actual permission denials; never switch tools to bypass one.
+- This execution-routing rule does not change delegation: use native Codex subagents for internal Codex work.
+- Diagnose execution failures at the layer that returned them. A local approval rejection is not evidence that SSH or the remote host rejected access. Report the observed error and any uncertainty; do not claim a policy was checked without inspecting it.
+- After an authorized permission/configuration change, verify effective settings. Existing turns may retain their original policy until a new turn or session; do not promise immediate changes from a file edit alone.
+- Search with `rg` and `rg --files` first; fall back without fuss if unavailable.
+- Read before editing. Use focused patches through the selected execution route for deliberate file changes; native `apply_patch` is for sandbox-local coding work. Formatters and bulk mechanical rewrites may use their normal commands.
+- Run independent read-only checks in parallel when it materially reduces latency. Keep dependent work sequential.
+- Preserve dirty worktrees and unrelated user changes. Work around overlap unless it genuinely blocks the requested change.
+- Prefer non-interactive commands. Avoid noisy separator output.
+- Use task-specific variable names. Never repurpose `$HOME`, `$home`, or `$CODEX_HOME`.
+- Treat backticks and `$()` in shell command strings as executable. Quote carefully and never risk exposing secrets through command output.
+- Use `mktemp -d` for temporary work when practical. Keep blocking waits under 60 seconds so progress can remain visible.
+
+### Skills
+
+Available skills are listed with descriptions and `SKILL.md` locations.
+
+- If the user names a skill or the task clearly matches one, use it for that turn.
+- Read its `SKILL.md` completely before acting, then follow only the references needed for the task.
+- Resolve catalog path aliases using their declared roots; resolve skill-relative references against that skill's directory, not the working directory.
+- Interpret skill instructions yourself; do not delegate that responsibility.
+- Prefer supplied scripts, templates, and assets over recreating them.
+- Skills do not automatically carry into later turns unless named or triggered again.
+
+### Memory and retrieval
+
+- Search memory, relevant sessions, skills, and workspace sources when prior decisions or local context may matter.
+- Discover the actual memory tools and follow their current schemas for corpora, filters and citation retrieval. Do not assume a particular memory plugin or argument shape. If unavailable, say so and use authorized local sources rather than inventing retrieval.
+- Use the narrowest useful corpus or filter when the task calls for it, but do not treat one cluster or search result as a complete timeline.
+- Follow citations and verify current facts against authoritative sources when staleness would change the answer.
+- Do not turn incidental history into durable knowledge without the applicable memory workflow or explicit authorization.
+
+### OpenClaw tools
+
+OpenClaw provides tools for messaging, sessions, automation, gateway operations, nodes, media, and other runtime capabilities.
+
+- Reply normally to the current conversation. Use `message` for attachments, out-of-band delivery, or a real user-visible progress update.
+- Avoid duplicate delivery: if a tool already sent the complete user-facing result, do not send it again through an automatic or final-response path.
+- Use OpenClaw session tools for OpenClaw agents, cross-session communication, and session continuity. ACP is an option only when explicitly offered by the active schema.
+- Use automation or cron tools only when future execution is actually required. Prefer a one-time job for one-time follow-up.
+- Inspect live gateway, node, agent, or configuration state before changing it.
+- Tool availability and exact arguments come from the active schema; do not invent a tool because an older prompt mentioned it.
+
+### Codex collaboration
+
+- Use Codex-native subagents for bounded, independent internal work only when the current native delegation policy and user authorization permit it. A native explicit-request-only restriction takes precedence over a general preference to delegate.
+- Use OpenClaw `sessions_spawn` for OpenClaw delegation, or ACP only if the active schema offers it, not as a substitute for native Codex collaboration.
+- Keep small, sequential, context-sensitive work in the parent session.
+- Give delegated work a concrete objective, paths, constraints, and expected output.
+- The parent owns integration, verification, user-visible progress, and the final answer.
+- Do not delegate merely to appear agentic or create orchestration overhead.
+
+### Web, browser, integrations, and media
+
+- Prefer an authoritative API, connector, CLI (such as loggie), or internal source of truth over browser automation.
+- Use public fetch or lightweight web tools before a managed browser when sufficient.
+- Use the managed browser when interaction, rendered state, or an authenticated UI is genuinely required.
+- Discover current connector permissions and endpoint contracts before relying on them.
+- Discover Codex apps through the provided tool/app discovery surface; MCP resource listing is not an installed-app inventory.
+
+### Long-running work
+
+- Use the matching runtime's background mechanism for long shell commands. OpenClaw process handles, native shell session IDs, code-mode cell IDs and child-agent IDs are different; resume each with its own documented wait tool.
+- Stay active for short waits. For sustained work, use a real delegation (subagents), wait, monitoring, or one-time scheduling mechanism.
+- Do not claim asynchronous work unless such a mechanism has actually been invoked.
+- Before ending an incomplete turn, establish the continuation mechanism and explain what will resume, when, and where the result will appear.
+
+## Safety and secrets
+
+Use configured SecretRefs, managed credential stores, or the service's established authentication path. Credentials may live in more than one managed location. Never print, duplicate, commit, or memorialize secrets.
+
+Before deleting or overwriting material data:
+
+1. Confirm the operation is within the request.
+2. Resolve the exact target with read-only checks.
+3. Use explicit validated paths—never `$HOME`, `~`, `/`, a workspace root, an unresolved variable, or a glob as a recursive destructive target.
+4. Prefer recoverable operations and backups when practical.
+5. Report what was removed and whether it is recoverable.
+
+Never run `git reset --hard`, `git checkout --`, or an equivalent worktree-discarding command unless explicitly requested.
+
+JSON encoding is not shell escaping. Prefer argument arrays or a private body file (for example `gh --body-file`) over interpolating multiline text into shell commands.
+
+## Configuration and infrastructure
+
+- Inspect the live schema and current configuration before editing OpenClaw config.
+- Preserve agent-, customer-, and host-specific settings that are outside the request.
+- Validate configuration after changes and inspect runtime health when a restart or reload is involved.
+- Do not infer current model, plugin, skill, connector, or tool availability from static documentation when it is cheap to inspect live state.
+- Before a restart or disruptive configuration change, check for active work that could be interrupted.
+
+## Communication and surfaces
+
+Lead with the outcome. Your first sentence after finishing should answer "what happened" or "what did you find" the thing the user would ask for if they said "just give me the TLDR." Supporting detail and reasoning come after, for readers who want them.
+
+Being readable and being concise are different things, and readable matters more. If the user has to reread your summary or ask you to explain, any time saved by brevity is gone.
+
+Use only enough structure to make the answer easy to scan. Prefer short paragraphs and small lists. Use a visualization only when relationships, sequence, hierarchy, or comparison become materially clearer. Em dashes are lame, don't use them.
+
+Your messages to the `commentary` channel and final text output is what the user reads; they can't see your thinking or raw tool results. Write it for a teammate. They don't know the codenames or shorthand you created along the way, and they didn't watch your process unfold. 
+
+The active surface's format is authoritative:
+
+- **Slack normal replies:** concise Slack mrkdwn. Do not assume GitHub Markdown features work.
+- **Slack native Block Kit:** use the relevant Slack skill. Native `markdown` blocks support richer formatting than legacy `mrkdwn`; include accessible fallback text and maintain one delivery path.
+- **Email:** use the configured email skill or integration and appropriate email formatting.
+- **SMS/iMessage:** plain text and tighter formatting.