@cmodjs/core 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jordan Parker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,12 @@
-# Temporary Holding Version
+# @cmodjs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The library Claude Code mods import. CMod is the Claude Mod Manager: it installs, tries, builds, checks, and publishes Claude Code mods, which are plugins with hooks, panes, commands, tools, permissions, and an install step that runs with your consent.
+
+```sh
+npm i -g @cmodjs/cli
+cmod new my-mod
+```
+
+`cmod new` writes a mod that depends on this package. A mod imports it by path, such as `../node_modules/@cmodjs/core/mod.js`, because Claude Code loads a plugin's own files only.
+
+The guide and the CMod plugin live at [github.com/heyJordanParker/cmod](https://github.com/heyJordanParker/cmod).

package/connect.d.ts

@@ -0,0 +1,4 @@
+import type { On } from 'claude-code';
+import type { ModDefinition } from './mod.js';
+export declare function connect<State extends object>(on: On, definition: ModDefinition<State>): void;
+//# sourceMappingURL=connect.d.ts.map

package/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["src/connect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoD,EAAE,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AA2E7C,wBAAgB,OAAO,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,IAAI,CA8B5F"}

package/connect.js

@@ -0,0 +1,98 @@
+import { createLifecycle, readPlugin } from './runtime/lifecycle.js';
+let lifecycle;
+async function start($, e, next) {
+    await lifecycle.start(claudeOf($), readPlugin);
+    return next(e);
+}
+function route(_$, e, next) {
+    return lifecycle.route(next.event, e, (passed) => next(passed));
+}
+function claudeOf($) {
+    return {
+        plugin: { name: $.plugin.name, root: $.plugin.root },
+        ui: {
+            toast: (text, options) => $.ui.toast(text, options),
+            status: (text) => $.ui.status(text),
+            log: (text, options) => $.ui.log(text, options),
+            notice: (toolUseId, text) => $.ui.notice(toolUseId, text),
+            invalidate: (event) => $.ui.invalidate(event),
+            ask: (question, options) => $.ui.ask(question, options),
+            open: (pane) => $.ui.open(pane),
+            close: (pane) => $.ui.close(pane),
+            panes: () => $.ui.panes(),
+            resolve: (render) => $.ui.resolve(render),
+        },
+        process: {
+            run: (argv, init) => $.process.run(argv, init),
+            spawn: (request) => $.process.spawn(request),
+        },
+        fs: {
+            read: (path) => $.fs.read(path),
+            write: (path, text) => $.fs.write(path, text),
+            list: (path) => $.fs.list(path),
+            exists: (path) => $.fs.exists(path),
+            stat: (path, options) => $.fs.stat(path, options),
+        },
+        http: { fetch: (url, init) => $.http.fetch(url, init) },
+        settings: { read: (args) => $.settings.read(args) },
+        store: {
+            get: (key) => $.store.get(key),
+            set: (key, value) => $.store.set(key, value),
+            delete: (key) => $.store.delete(key),
+            keys: () => $.store.keys(),
+        },
+        clock: {
+            now: () => $.clock.now(),
+            after: (ms, fn) => $.clock.after(ms, fn),
+            every: (ms, fn) => $.clock.every(ms, fn),
+        },
+        session: {
+            id: () => $.session.id(),
+            root: () => $.session.root(),
+            cwd: () => $.session.cwd(),
+            model: () => $.session.model(),
+            usage: () => $.session.usage(),
+            surfaces: () => $.session.surfaces(),
+        },
+        command: { register: (command) => $.command.register(command) },
+        tool: { register: (tool) => $.tool.register(tool) },
+        agent: { list: () => $.agent.list() },
+        env: {
+            home: () => $.env.get('HOME'),
+            dataHome: () => $.env.get('XDG_DATA_HOME'),
+            configHome: () => $.env.get('CLAUDE_CONFIG_DIR'),
+        },
+        cmod: { call: (input) => $.cmod.call(input) },
+    };
+}
+export function connect(on, definition) {
+    lifecycle = createLifecycle(definition);
+    on('session.start', start);
+    on('classic.SessionStart', route);
+    on('classic.SessionEnd', route);
+    on('classic.UserPromptSubmit', route);
+    on('classic.InstructionsLoaded', route);
+    on('classic.PreToolUse', route);
+    on('classic.PermissionRequest', route);
+    on('classic.PermissionDenied', route);
+    on('classic.PostToolUse', route);
+    on('classic.PostToolUseFailure', route);
+    on('classic.PostToolBatch', route);
+    on('classic.SubagentStart', route);
+    on('classic.SubagentStop', route);
+    on('classic.Notification', route);
+    on('classic.PreCompact', route);
+    on('classic.Stop', route);
+    on('classic.StopFailure', route);
+    on('tool.check', route);
+    on('tool.call', route);
+    on('prompt.submit', route);
+    on('prompt.context', route);
+    on('command.run', route);
+    on('session.measure', route);
+    on('skill.prompt', route);
+    on('ui.render', route);
+    on('ui.press', route);
+    on('ui.close', route);
+    on('cmod.call', route);
+}

package/jobs/check.d.ts

@@ -0,0 +1,8 @@
+import type { Part } from '../mod.js';
+import { type Target } from './permissions/match-target.js';
+export declare function check<State extends object = Record<never, never>>(options: {
+    readonly after: Target | Target[];
+    readonly run: readonly string[];
+    readonly timeoutMs?: number;
+}): Part<void, State>;
+//# sourceMappingURL=check.d.ts.map

package/jobs/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/jobs/check.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAOrC,OAAO,EAAyB,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAIlF,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CA4BlM"}

package/jobs/check.js

@@ -0,0 +1,60 @@
+import { longestMs } from '../runtime/deadline.js';
+import { callEffects } from '../utils/call-effects.js';
+import { parentOf } from '../utils/paths.js';
+import { listed, messageOf } from '../utils/text.js';
+import { afterCall, modOf, targetWords } from './part-context.js';
+import { matchTarget, targetOf } from './permissions/match-target.js';
+const defaultMs = 60_000;
+export function check(options) {
+    const { after, run, timeoutMs = defaultMs } = options;
+    const targets = Array.isArray(after) ? after : [after];
+    if (targets.length === 0)
+        throw new Error("check: give after a target, such as { write: '**/*.ts' }.");
+    for (const target of targets)
+        targetOf(target);
+    const named = `check after ${listed(targets.map(targetWords))}`;
+    if (run.length === 0)
+        throw new Error(`check: the ${named} has no command. Give run a command, such as ['bun', 'test'].`);
+    if (!(timeoutMs > 0 && timeoutMs <= longestMs))
+        throw new Error(`check: the ${named} has timeoutMs ${timeoutMs}. Set it above 0 and at most ${longestMs} (${longestMs / 60_000} minutes).`);
+    const deadline = { ms: timeoutMs, job: 'check' };
+    return (context) => {
+        afterCall(context, async (use, workspace) => {
+            const triggered = await triggeredRun(targets, run, use, workspace);
+            if (triggered === undefined)
+                return [];
+            try {
+                const { command, folder } = triggered;
+                const { exitCode, stdout, stderr } = await modOf(context, { folder }, workspace, deadline).process.run(command);
+                return exitCode === 0 ? [] : [`${command.join(' ')} exited with ${exitCode}:\n${`${stdout}${stderr}`.trim()}`];
+            }
+            catch (error) {
+                return [`The ${named} failed: ${messageOf(error)}`];
+            }
+        }, (error) => [`The check job failed, so the ${named} did not run: ${messageOf(error)}`]);
+        context.announce(`a ${named}`);
+    };
+}
+async function triggeredRun(after, run, use, workspace) {
+    const effects = callEffects(use, workspace);
+    const paths = new Set();
+    let commandFolder;
+    for (const target of after) {
+        const matched = await matchTarget(target, use, effects, workspace);
+        const { key } = targetOf(target);
+        if (key !== 'read' && key !== 'write')
+            commandFolder ??= matched[0]?.folder;
+        else
+            for (const { call } of matched)
+                if ('path' in call)
+                    paths.add(call.path);
+    }
+    const existing = [];
+    for (const path of paths)
+        if (await workspace.fs.exists(path))
+            existing.push(path);
+    const last = existing.at(-1);
+    if (last !== undefined)
+        return { command: [...run, ...existing], folder: parentOf(last) };
+    return commandFolder === undefined ? undefined : { command: [...run], folder: commandFolder };
+}

package/jobs/part-context.d.ts

@@ -0,0 +1,14 @@
+import type { Mod, PartContext } from '../mod.js';
+import { type Deadline } from '../runtime/deadline.js';
+import type { ToolCall, ToolUse } from '../utils/call-effects.js';
+import { type Workspace } from './permissions/find-project-scope.js';
+import { type Target } from './permissions/match-target.js';
+export declare function workspaceReader({ claude }: PartContext): () => Promise<Workspace>;
+export declare function afterCall<State extends object>(part: PartContext<State>, contextAfter: (use: ToolUse, workspace: Workspace) => Promise<readonly string[]>, failed: (error: unknown) => readonly string[]): void;
+export declare function modOf<State extends object>(context: PartContext<State>, { call, folder }: {
+    readonly call?: ToolCall;
+    readonly folder: string;
+}, workspace: Workspace, deadline: Deadline): Mod<State>;
+export declare function modWithin<State extends object>({ mod, claude }: PartContext<State>, deadline: Deadline, workTree?: () => Promise<string | undefined>): Mod<State>;
+export declare function targetWords(target: Target): string;
+//# sourceMappingURL=part-context.d.ts.map

package/jobs/part-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"part-context.d.ts","sourceRoot":"","sources":["../src/jobs/part-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAEjD,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAItE,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACjE,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,qCAAqC,CAAA;AACtF,OAAO,EAAY,KAAK,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAOrE,wBAAgB,eAAe,CAAC,EAAE,MAAM,EAAE,EAAE,WAAW,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAOjF;AAaD,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAC5C,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,EACxB,YAAY,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,EAChF,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,MAAM,EAAE,GAC5C,IAAI,CAUN;AAMD,wBAAgB,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,CAEtM;AAED,wBAAgB,SAAS,CAAC,KAAK,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAyB,GAAG,GAAG,CAAC,KAAK,CAAC,CAwBxL;AAwBD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD"}

package/jobs/part-context.js

@@ -0,0 +1,106 @@
+import { beforeDeadline } from '../runtime/deadline.js';
+import { dependencyCalls } from '../runtime/dependencies.js';
+import { toolInputOf } from '../runtime/tool-calls.js';
+import { listed } from '../utils/text.js';
+import { findProjectScope } from './permissions/find-project-scope.js';
+import { targetOf } from './permissions/match-target.js';
+export function workspaceReader({ claude }) {
+    let session;
+    return async () => {
+        session ??= readSession(claude);
+        const [{ home, scope, fs }, projectRoot, cwd] = await Promise.all([session, claude.session.root(), claude.session.cwd()]);
+        return { projectRoot, cwd, home, fs, scope };
+    };
+}
+async function readSession(claude) {
+    const fs = {
+        read: (path) => claude.fs.read(path),
+        stat: (path) => claude.fs.stat(path, { resolve: true }),
+        exists: (path) => claude.fs.exists(path),
+    };
+    const home = await claude.env.home();
+    if (home === undefined)
+        throw new Error('HOME is not set, so ~ in a path has no meaning. Start Claude Code with HOME set.');
+    return { home, fs, scope: await findProjectScope(claude.plugin.root, home, fs) };
+}
+export function afterCall(part, contextAfter, failed) {
+    const readWorkspace = workspaceReader(part);
+    part.on('tool.call', async (e, next) => {
+        const before = Promise.all([useOf(part, e), readWorkspace()]);
+        await before.catch(() => undefined);
+        const result = await next(e);
+        if (result.deny !== undefined || result.isError === true)
+            return result;
+        const added = await before.then(([use, workspace]) => contextAfter(use, workspace)).catch(failed);
+        return added.length === 0 ? result : { ...result, context: [...(result.context ?? []), ...added] };
+    });
+}
+async function useOf({ toolCalls }, e) {
+    return { tool: e.tool, input: toolInputOf(e), ...(await toolCalls.agentOf(e.tool_use_id)) };
+}
+export function modOf(context, { call, folder }, workspace, deadline) {
+    return modWithin(context, deadline, async () => workspace.scope?.workTreeOf(call !== undefined && 'path' in call ? call.path : folder));
+}
+export function modWithin({ mod, claude }, deadline, workTree = async () => undefined) {
+    const within = (call, task) => beforeDeadline(claude, deadline, call, task);
+    const folderOf = async (cwd) => {
+        const folder = cwd ?? (await workTree());
+        return folder === undefined ? {} : { cwd: folder };
+    };
+    const overrides = {
+        process: {
+            async run(argv, init) {
+                const folder = await folderOf(init?.cwd);
+                const timeoutMs = Math.min(init?.timeoutMs ?? deadline.ms, deadline.longestMs ?? deadline.ms);
+                return beforeDeadline(claude, { ...deadline, ms: timeoutMs }, 'mod.process.run', mod.process.run(argv, { ...init, ...folder, timeoutMs }));
+            },
+            spawn: (argv, init) => spawnWithin(claude, deadline, folderOf(init?.cwd).then((folder) => mod.process.spawn(argv, { ...init, ...folder }))),
+        },
+        fs: {
+            read: (path) => within('mod.fs.read', mod.fs.read(path)),
+            write: (path, text) => within('mod.fs.write', mod.fs.write(path, text)),
+            list: (path) => within('mod.fs.list', mod.fs.list(path)),
+        },
+        http: { fetch: (url, init) => within('mod.http.fetch', mod.http.fetch(url, init)) },
+        dependencies: dependencyCalls(claude, within),
+    };
+    return Object.assign(Object.create(mod), overrides);
+}
+function spawnWithin(claude, deadline, started) {
+    async function* pieces() {
+        const stream = await started;
+        let finish = () => undefined;
+        const running = beforeDeadline(claude, deadline, 'mod.process.spawn', new Promise((resolve) => (finish = resolve)));
+        const passed = running.then(() => new Promise(() => undefined));
+        try {
+            for (;;) {
+                const piece = await Promise.race([stream.next(), passed]);
+                if (piece.done === true)
+                    return piece.value;
+                yield piece.value;
+            }
+        }
+        finally {
+            finish();
+            void stream.return?.();
+        }
+    }
+    const result = started.then((stream) => stream.result);
+    result.catch(() => undefined);
+    return Object.assign(pieces(), { result });
+}
+export function targetWords(target) {
+    const { key, patterns } = targetOf(target);
+    const named = listed(patterns);
+    if (key === 'command')
+        return patterns.includes('*') ? 'every shell command' : named;
+    if (key === 'write')
+        return `edits to ${named}`;
+    if (key === 'read')
+        return `reads of ${named}`;
+    if (key === 'fetch')
+        return `fetches of ${named}`;
+    if (key === 'subagent')
+        return `the ${named} subagent`;
+    return `the ${named} tool`;
+}

package/jobs/permissions/decide-permission.d.ts

@@ -0,0 +1,21 @@
+import { type ToolCall, type ToolUse } from '../../utils/call-effects.js';
+import type { Workspace } from './find-project-scope.js';
+import { type TargetCalls, type TargetKey, type TargetOf } from './match-target.js';
+export type Rule<Mod> = {
+    [Key in TargetKey]: TargetOf<Key> & {
+        when?: (call: TargetCalls[Key], mod: Mod) => boolean | Promise<boolean>;
+        reason?: string;
+    };
+}[TargetKey];
+export type PermissionRules<Mod> = {
+    deny?: Rule<Mod>[];
+    ask?: Rule<Mod>[];
+};
+export type Decision = 'allow' | 'ask' | 'deny';
+export type Verdict = {
+    decision: Decision;
+    reason?: string;
+};
+export declare function stricterVerdict<Result extends Verdict>(first: Result, second: Result): Result;
+export declare function decidePermission<Mod>(rules: PermissionRules<Mod>, use: ToolUse, workspace: Workspace, modOf: (call: ToolCall, folder: string) => Mod): Promise<Verdict | undefined>;
+//# sourceMappingURL=decide-permission.d.ts.map

package/jobs/permissions/decide-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide-permission.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/decide-permission.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6C,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,6BAA6B,CAAA;AACpH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAuE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAGxJ,MAAM,MAAM,IAAI,CAAC,GAAG,IAAI;KACrB,GAAG,IAAI,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG;QAClC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;QACvE,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB;CACF,CAAC,SAAS,CAAC,CAAA;AAEZ,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI;IAAE,IAAI,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;CAAE,CAAA;AAC5E,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAA;AAC/C,MAAM,MAAM,OAAO,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAI7D,wBAAgB,eAAe,CAAC,MAAM,SAAS,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7F;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,KAAK,GAAG,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAezL"}

package/jobs/permissions/decide-permission.js

@@ -0,0 +1,71 @@
+import { strictness } from '../../runtime/hooks.js';
+import { messageOf } from '../../utils/text.js';
+import { callBaseOf, callEffects } from '../../utils/call-effects.js';
+import { folderInScope, matchTarget, targetOf } from './match-target.js';
+import { resolvePath } from '../../utils/paths.js';
+const wordBoundary = '\\s;&|()<>\'"`=';
+export function stricterVerdict(first, second) {
+    return strictness.indexOf(second.decision) > strictness.indexOf(first.decision) ? second : first;
+}
+export async function decidePermission(rules, use, workspace, modOf) {
+    try {
+        const effects = callEffects(use, workspace);
+        for (const decision of ['deny', 'ask']) {
+            for (const rule of rules[decision] ?? []) {
+                const outcome = await ruleOutcome(rule, use, effects, workspace, modOf);
+                if (outcome === undefined)
+                    continue;
+                const reason = [rule.reason, outcome.failure === undefined ? undefined : `Its when check failed: ${outcome.failure}`].filter((part) => part !== undefined).join(' ');
+                return reason === '' ? { decision } : { decision, reason };
+            }
+        }
+        return undefined;
+    }
+    catch (error) {
+        return { decision: 'deny', reason: `The permissions job failed, so it denies the call: ${messageOf(error)}` };
+    }
+}
+async function ruleOutcome(rule, use, effects, workspace, modOf) {
+    const matched = await matchTarget(rule, use, effects, workspace);
+    const calls = matched.length > 0 ? matched : await unparsedMatches(rule, use, effects, workspace);
+    if (calls.length === 0)
+        return undefined;
+    const { when } = rule;
+    if (when === undefined)
+        return { failure: undefined };
+    for (const { call, access, folder } of calls) {
+        const fullCall = access?.contents === undefined ? call : { ...call, ...(await access.contents()) };
+        try {
+            if (await when(fullCall, modOf(fullCall, folder)))
+                return { failure: undefined };
+        }
+        catch (error) {
+            return { failure: messageOf(error) };
+        }
+    }
+    return undefined;
+}
+async function unparsedMatches(target, use, effects, workspace) {
+    const shell = effects.shell;
+    if (shell === undefined || shell.isFullyParsed)
+        return [];
+    const { key, patterns } = targetOf(target);
+    const base = callBaseOf(use);
+    if (key === 'command') {
+        const isMatched = patterns.some((pattern) => pattern.split(/\s+/).filter((word) => word !== '').every((word) => containsWord(shell.line, word)));
+        const folder = isMatched ? await folderInScope(shell, workspace) : undefined;
+        return folder === undefined ? [] : [{ call: { ...base, commands: shell.commands.map((command) => command.argv), isFullyParsed: false }, access: undefined, folder }];
+    }
+    if (key !== 'read' && key !== 'write')
+        return [];
+    const line = shell.line.toLowerCase();
+    const named = patterns.map((pattern) => pattern.slice(pattern.lastIndexOf('/') + 1)).filter((segment) => segment !== '' && !/[*?[\]{}]/.test(segment) && line.includes(segment.toLowerCase()));
+    const folder = named.length === 0 ? undefined : await folderInScope(shell, workspace);
+    if (folder === undefined)
+        return [];
+    return named.map((segment) => ({ call: { ...base, path: resolvePath(segment, folder) }, access: undefined, folder }));
+}
+function containsWord(line, word) {
+    const escaped = word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[${wordBoundary}/])${escaped}(?=$|[${wordBoundary}])`).test(line);
+}

package/jobs/permissions/find-project-scope.d.ts

@@ -0,0 +1,13 @@
+import { type FileSystem } from '../../utils/paths.js';
+export type ProjectScope = {
+    workTreeOf: (path: string) => Promise<string | undefined>;
+};
+export type Workspace = {
+    projectRoot: string;
+    cwd: string;
+    home: string;
+    fs: FileSystem;
+    scope: ProjectScope | undefined;
+};
+export declare function findProjectScope(pluginRoot: string, home: string, fs: FileSystem): Promise<ProjectScope | undefined>;
+//# sourceMappingURL=find-project-scope.d.ts.map

package/jobs/permissions/find-project-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-project-scope.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/find-project-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAErF,MAAM,MAAM,YAAY,GAAG;IAAE,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAAE,CAAA;AAExF,MAAM,MAAM,SAAS,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;CAAE,CAAA;AAE3H,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAwB1H"}

package/jobs/permissions/find-project-scope.js

@@ -0,0 +1,51 @@
+import { nameOf, parentOf, resolvePath } from '../../utils/paths.js';
+export async function findProjectScope(pluginRoot, home, fs) {
+    const skills = parentOf(pluginRoot);
+    const claude = parentOf(skills);
+    const root = parentOf(claude);
+    if (nameOf(skills) !== 'skills' || nameOf(claude) !== '.claude' || root === resolvePath(home, '/'))
+        return undefined;
+    const repositories = new Map();
+    const repositoryOf = async (workTree) => {
+        const known = repositories.get(workTree);
+        if (known !== undefined)
+            return known;
+        const repository = await readRepository(workTree, fs);
+        if (repository !== undefined)
+            repositories.set(workTree, repository);
+        return repository;
+    };
+    const project = await repositoryOf(root);
+    if (project === undefined)
+        return undefined;
+    return {
+        async workTreeOf(path) {
+            for (let folder = path;; folder = parentOf(folder)) {
+                const repository = await repositoryOf(folder);
+                if (repository !== undefined)
+                    return repository === project ? folder : undefined;
+                if (folder === '/')
+                    return undefined;
+            }
+        },
+    };
+}
+async function readRepository(workTree, fs) {
+    const gitPath = resolvePath('.git', workTree);
+    const git = await fs.stat(gitPath).catch(() => undefined);
+    if (git === undefined)
+        return undefined;
+    if (git.kind === 'dir')
+        return git.realPath ?? gitPath;
+    try {
+        const gitDirectory = /^gitdir:\s*(.+)$/m.exec(await fs.read(gitPath))?.[1]?.trim();
+        if (gitDirectory === undefined)
+            throw new Error(`${gitPath} has no gitdir line.`);
+        const linkedDirectory = resolvePath(gitDirectory, workTree);
+        const commonDirectory = await fs.read(resolvePath('commondir', linkedDirectory)).then((text) => resolvePath(text.trim(), linkedDirectory), () => linkedDirectory);
+        return (await fs.stat(commonDirectory)).realPath ?? commonDirectory;
+    }
+    catch {
+        return workTree;
+    }
+}

package/jobs/permissions/match-target.d.ts

@@ -0,0 +1,27 @@
+import { type CallBase, type CallEffects, type CommandCall, type FetchCall, type FileAccess, type FileCall, type ToolCall, type ToolUse } from '../../utils/call-effects.js';
+import type { Workspace } from './find-project-scope.js';
+export type TargetCalls = {
+    command: CommandCall;
+    read: FileCall;
+    write: FileCall;
+    fetch: FetchCall;
+    subagent: CallBase;
+    tool: CallBase;
+};
+export type TargetKey = keyof TargetCalls;
+export type TargetOf<Key extends TargetKey> = Record<Key, string | string[]> & Partial<Record<Exclude<TargetKey, Key>, never>>;
+export type Target = {
+    [Key in TargetKey]: TargetOf<Key>;
+}[TargetKey];
+export type MatchedCall = {
+    call: ToolCall;
+    access: FileAccess | undefined;
+    folder: string;
+};
+export declare function targetOf(target: Target): {
+    key: TargetKey;
+    patterns: string[];
+};
+export declare function matchTarget(target: Target, use: ToolUse, effects: CallEffects, workspace: Workspace): Promise<MatchedCall[]>;
+export declare function folderInScope(shell: NonNullable<CallEffects['shell']>, workspace: Workspace): Promise<string | undefined>;
+//# sourceMappingURL=match-target.d.ts.map

package/jobs/permissions/match-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-target.d.ts","sourceRoot":"","sources":["../../src/jobs/permissions/match-target.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,MAAM,6BAA6B,CAAA;AACxL,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAGxD,MAAM,MAAM,WAAW,GAAG;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAA;AACzI,MAAM,MAAM,SAAS,GAAG,MAAM,WAAW,CAAA;AACzC,MAAM,MAAM,QAAQ,CAAC,GAAG,SAAS,SAAS,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAA;AAC9H,MAAM,MAAM,MAAM,GAAG;KAAG,GAAG,IAAI,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC;CAAE,CAAC,SAAS,CAAC,CAAA;AACrE,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAI5F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAQ/E;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CA6BlI;AA4BD,wBAAsB,aAAa,CAAC,KAAK,EAAE,WAAW,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAI/H"}