@phyzess/pappra 0.1.0-beta.6 → 0.1.0-beta.8

package/README.md

@@ -63,7 +63,7 @@ requires an explicit controller. They are not needed for the core workflow above
 - **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
 - **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
 - **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
-- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle --marketplace` exports a local marketplace that Claude Code and Codex accept, without registering it. `host install --mode plugin` fails closed with per-host evidence; see [host plugin validation](docs/host-plugin-validation.md).
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle into the host root; `host bundle --marketplace` exports a local marketplace that Claude Code and Codex accept, without registering it. Plugin hooks are verified for Pi 1.3.0 and Claude Code 2.1.292 (startup); Codex 0.163.0 loads hooks only from user scope, so use `host install --host codex --scope user` (merges `$CODEX_HOME/hooks.json`). `host bundle` exports a plugin bundle for the other hosts and `host install --mode plugin` fails closed with the per-host commands. See [host plugin validation](docs/host-plugin-validation.md).
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -87,7 +87,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.6`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.6`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.8`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.8`, because pre-release versions are never republished.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/dist/cli/commands/host.d.ts

@@ -12,5 +12,6 @@ export interface HostCommandOptions {
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
     readonly marketplace: boolean;
+    readonly scope: 'project' | 'user' | null;
 }
 export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { HostIntegrationService } from '../../hosts/integration/service.js';
 import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.js';
 import { HOST_SUPPORT, isSupportedVersion, } from '../../hosts/integration/support.js';
@@ -10,6 +10,13 @@ export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundl
     '\n' +
     'bundle exports a host-native plugin/package directory and never registers it or\n' +
     'claims host callability.';
+/** Codex only loads lifecycle hooks from its user configuration directory. */
+function codexHome() {
+    const configured = process.env['CODEX_HOME'];
+    return configured === undefined || configured === ''
+        ? join(homedir(), '.codex')
+        : resolve(configured);
+}
 function printDiagnostics(output, diagnostics) {
     for (const entry of diagnostics) {
         if (typeof entry === 'object' &&
@@ -46,9 +53,27 @@ export async function runHostCommand(options, output) {
         hostVersion: options.hostVersion,
         observedAt: new Date().toISOString(),
     });
-    const hostRoot = options.hostRoot === null
-        ? undefined
-        : resolve(options.cwd, options.hostRoot);
+    if (options.scope === 'user') {
+        if (HOST_SUPPORT[options.host].hookScope !== 'user') {
+            output.stderr(`pappra host: ${options.host} loads hooks from ${HOST_SUPPORT[options.host].hookScope} scope; --scope user is only valid for a user-scoped host (codex).\n`);
+            return 2;
+        }
+        if (options.hostRoot !== null) {
+            output.stderr('pappra host: --scope user resolves CODEX_HOME and cannot be combined with --host-root.\n');
+            return 2;
+        }
+        if (options.action !== 'plan' &&
+            options.action !== 'install' &&
+            options.action !== 'verify') {
+            output.stderr('pappra host: --scope user is only valid for plan, install, or verify.\n');
+            return 2;
+        }
+    }
+    const hostRoot = options.scope === 'user'
+        ? codexHome()
+        : options.hostRoot === null
+            ? undefined
+            : resolve(options.cwd, options.hostRoot);
     const target = {
         ...(hostRoot === undefined ? {} : { hostRoot }),
         ...(options.hostVersion === null

package/dist/cli/run.js

@@ -26,6 +26,7 @@ function parseOptions(args) {
             out: { type: 'string' },
             mode: { type: 'string' },
             marketplace: { type: 'boolean' },
+            scope: { type: 'string' },
             bind: { type: 'boolean' },
             force: { type: 'boolean' },
             'no-interactive': { type: 'boolean' },
@@ -251,6 +252,16 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--out is only valid for host.');
         return 2;
     }
+    if (values.scope !== undefined &&
+        values.scope !== 'project' &&
+        values.scope !== 'user') {
+        failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
+        return 2;
+    }
+    if (command !== 'host' && values.scope !== undefined) {
+        failure(output, json, 'invalid_arguments', '--scope is only valid for host.');
+        return 2;
+    }
     if (command !== 'host' && values.marketplace === true) {
         failure(output, json, 'invalid_arguments', '--marketplace is only valid for host bundle.');
         return 2;
@@ -665,6 +676,10 @@ export async function runCli(args, output) {
             (values.apply === true && action !== 'install') ||
             (values.mode !== undefined && action !== 'install') ||
             (values.marketplace === true && action !== 'bundle') ||
+            (values.scope !== undefined &&
+                action !== 'plan' &&
+                action !== 'install' &&
+                action !== 'verify') ||
             (values['host-root'] !== undefined && action === null) ||
             (values['host-version'] !== undefined && action === null);
         if (values.help) {
@@ -693,6 +708,9 @@ export async function runCli(args, output) {
                 ? values.mode
                 : null,
             marketplace: values.marketplace === true,
+            scope: values.scope === 'project' || values.scope === 'user'
+                ? values.scope
+                : null,
         }, output);
     }
     if (command !== null) {

package/dist/hosts/integration/pappra-extension-runtime.mjs

@@ -23933,6 +23933,7 @@ var HOST_SUPPORT = {
   pi: {
     surface: "pi-extension",
     version: "1.3.0",
+    hookScope: "project",
     events: {
       startup: "session_start",
       resume: "session_start",
@@ -23943,6 +23944,9 @@ var HOST_SUPPORT = {
   codex: {
     surface: "codex-hooks",
     version: "0.163.0",
+    // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+    // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+    hookScope: "user",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",
@@ -23953,6 +23957,7 @@ var HOST_SUPPORT = {
   claude: {
     surface: "claude-hooks",
     version: "2.1.292",
+    hookScope: "project",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",

package/dist/hosts/integration/pappra-hook.mjs

@@ -23938,6 +23938,7 @@ var HOST_SUPPORT = {
   pi: {
     surface: "pi-extension",
     version: "1.3.0",
+    hookScope: "project",
     events: {
       startup: "session_start",
       resume: "session_start",
@@ -23948,6 +23949,9 @@ var HOST_SUPPORT = {
   codex: {
     surface: "codex-hooks",
     version: "0.163.0",
+    // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+    // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+    hookScope: "user",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",
@@ -23958,6 +23962,7 @@ var HOST_SUPPORT = {
   claude: {
     surface: "claude-hooks",
     version: "2.1.292",
+    hookScope: "project",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",

package/dist/hosts/integration/service.js

@@ -886,11 +886,13 @@ export class HostIntegrationService {
     async install(host, options) {
         if (options.mode === 'plugin') {
             const support = HOST_PLUGIN_HOOKS[host];
-            const guidance = support.state === 'verified'
-                ? 'Export the package with `pappra host bundle --host pi --out <dir> --json`, then run `pi install <dir> -l -a`; project-settings install is still available with --mode project-settings.'
-                : support.state === 'unsupported'
-                    ? 'This host does not load plugin hooks at its pinned version; keep --mode project-settings. See docs/host-plugin-validation.md.'
-                    : 'Plugin hooks are not verified for this host yet; an authenticated lifecycle session is required. Use --mode project-settings meanwhile.';
+            const guidance = host === 'claude' && support.state === 'verified'
+                ? 'Export with `pappra host bundle --host claude --out <dir> --marketplace --json`, then run `claude plugin marketplace add <dir>` and `claude plugin install pappra@pappra-local`. Use --mode project-settings for automatic workspace wiring.'
+                : host === 'pi' && support.state === 'verified'
+                    ? 'Export with `pappra host bundle --host pi --out <dir> --json`, then run `pi install <dir> -l -a`. Use --mode project-settings for automatic workspace wiring.'
+                    : support.state === 'unsupported'
+                        ? 'This host does not load plugin hooks at its pinned version; keep --mode project-settings. See docs/host-plugin-validation.md.'
+                        : 'Plugin hooks are not verified for this host yet; an authenticated lifecycle session is required. Use --mode project-settings meanwhile.';
             return hostIntegrationResultSchema.parse({
                 schema: 'pappra/host-integration/1',
                 ok: false,

package/dist/hosts/integration/support.d.ts

@@ -3,6 +3,7 @@ export declare const HOST_SUPPORT: {
     readonly pi: {
         readonly surface: 'pi-extension';
         readonly version: '1.3.0';
+        readonly hookScope: 'project';
         readonly events: {
             readonly startup: 'session_start';
             readonly resume: 'session_start';
@@ -13,6 +14,7 @@ export declare const HOST_SUPPORT: {
     readonly codex: {
         readonly surface: 'codex-hooks';
         readonly version: '0.163.0';
+        readonly hookScope: 'user';
         readonly events: {
             readonly startup: 'SessionStart';
             readonly resume: 'SessionStart';
@@ -23,6 +25,7 @@ export declare const HOST_SUPPORT: {
     readonly claude: {
         readonly surface: 'claude-hooks';
         readonly version: '2.1.292';
+        readonly hookScope: 'project';
         readonly events: {
             readonly startup: 'SessionStart';
             readonly resume: 'SessionStart';
@@ -50,7 +53,7 @@ export declare const HOST_PLUGIN_HOOKS: {
         readonly evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.';
     };
     readonly claude: {
-        readonly state: 'unverified';
-        readonly evidence: 'Claude Code 2.1.292 validation passes, but no authenticated session was available to run a lifecycle event.';
+        readonly state: 'verified';
+        readonly evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.';
     };
 };

package/dist/hosts/integration/support.js

@@ -2,6 +2,7 @@ export const HOST_SUPPORT = {
     pi: {
         surface: 'pi-extension',
         version: '1.3.0',
+        hookScope: 'project',
         events: {
             startup: 'session_start',
             resume: 'session_start',
@@ -12,6 +13,9 @@ export const HOST_SUPPORT = {
     codex: {
         surface: 'codex-hooks',
         version: '0.163.0',
+        // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+        // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+        hookScope: 'user',
         events: {
             startup: 'SessionStart',
             resume: 'SessionStart',
@@ -22,6 +26,7 @@ export const HOST_SUPPORT = {
     claude: {
         surface: 'claude-hooks',
         version: '2.1.292',
+        hookScope: 'project',
         events: {
             startup: 'SessionStart',
             resume: 'SessionStart',
@@ -55,7 +60,7 @@ export const HOST_PLUGIN_HOOKS = {
         evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.',
     },
     claude: {
-        state: 'unverified',
-        evidence: 'Claude Code 2.1.292 validation passes, but no authenticated session was available to run a lifecycle event.',
+        state: 'verified',
+        evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.',
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.8",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"