@theokit/sdk 4.63.3 → 4.63.4

package/dist/internal/runtime/compat/foreign-config-sources.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The foreign configuration dialects this SDK can read, and what each one PRESUMES.
+ *
+ * ## Why a registry and not a list of directory names
+ *
+ * `projectConfigRoots` returned `[".theokit", ".claude"]` — two paths — and that shape is what
+ * usetheokit/theokit-sdk#522 fell through. A path says WHERE a file lives. It does not say how the
+ * file is parsed, and it does not say what runtime the commands inside it were written against.
+ *
+ * Claude Code defines `$CLAUDE_PROJECT_DIR` for the hook commands in its `settings.json`, and its
+ * documentation tells authors to reach project files through it — an absolute path would break for
+ * every other person on the team, so the shape that failed here is the shape upstream recommends.
+ * This SDK read the file and ran the command without the variable. `sh` expands an unset variable to
+ * the empty string, so
+ *
+ *     bash "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh"   became   bash "/.claude/hooks/guard.sh"
+ *
+ * which does not exist, which a hook runner correctly reads as a refusal. Every turn denied, in any
+ * repository that also had Claude Code set up, with a message naming a file that was present and
+ * executable all along.
+ *
+ * Importing a format means accepting the contract that format presumes. An adapter is where that
+ * contract is written down, so the next dialect (`.codex/` is the obvious one) declares its own
+ * instead of inheriting a hole.
+ *
+ * ## What an adapter deliberately does NOT do
+ *
+ * It does not make the foreign source trusted, and it does not make its hooks permissive: a script
+ * that exits non-zero is still a refusal. It supplies the variables the format's authors were
+ * entitled to assume, and nothing else — `env` here is merged over the scrubbed inherit policy by
+ * `spawnAndCollect`, so it adds names rather than widening what a child can see.
+ *
+ * @internal
+ */
+/** The Claude Code CLI's project configuration directory. */
+export declare const CLAUDE_DIR_NAME = ".claude";
+/** A configuration dialect this SDK understands. `theokit` is native; the rest are foreign. */
+export interface ConfigSourceAdapter {
+    /** Stable identifier, and what a consumer names to opt in. */
+    readonly kind: string;
+    /** The project-relative directory the dialect keeps its configuration in. */
+    readonly dirName: string;
+    /**
+     * Variables the dialect's own runtime defines for commands it executes.
+     *
+     * Empty for the native source: a `.theokit/` hook is written against THIS runtime and inherits it
+     * already. Non-empty is what makes a foreign command runnable rather than silently broken.
+     */
+    runtimeEnv(cwd: string): Record<string, string>;
+}
+/** The native source. Always read, never opted into, always first for precedence. */
+export declare const NATIVE_SOURCE: ConfigSourceAdapter;
+/**
+ * Claude Code.
+ *
+ * `CLAUDE_PROJECT_DIR` is the documented way for a hook command in `settings.json` to reach a file
+ * in the project. Only that one variable is supplied: `$CLAUDE_PLUGIN_ROOT` and the rest of that
+ * runtime's surface are NOT defined here, because supplying a name whose value this SDK would have
+ * to invent is worse than leaving it unset — an invented root sends a script somewhere real and
+ * wrong, where an unset one fails loudly.
+ */
+export declare const CLAUDE_CODE_SOURCE: ConfigSourceAdapter;
+/**
+ * The adapter whose directory an absolute config path sits under, or `undefined` for a path that
+ * belongs to no registered dialect.
+ *
+ * Matched on the path SEGMENT rather than with `includes`, so a workspace that happens to live under
+ * `/home/me/.claude-backups/repo` does not read as a Claude Code source.
+ */
+export declare function adapterForConfigPath(path: string): ConfigSourceAdapter | undefined;
+/**
+ * Variable references in a shell command that nothing will define.
+ *
+ * The second half of #522, and the half that cost the debugging session. `sh` expands an unset
+ * variable to the empty string and says nothing, so the failure surfaces ten characters later as a
+ * path: `bash: /.claude/hooks/guard.sh: No such file or directory` — which reads as "your script is
+ * missing" while the script is present and executable. Nothing in that message contains the name of
+ * the variable that was actually missing, so the reader looks in the wrong place.
+ *
+ * Checked against BOTH the process environment and the variables the dialect supplies, because
+ * either is a legitimate source: a hook may reasonably use `$HOME`.
+ *
+ * ## What it deliberately does not try to be
+ *
+ * This is not a shell parser. It finds `$NAME` and `${NAME}` outside single quotes, which is the
+ * shape a config file's hook commands take. It does NOT understand `${NAME:-default}` (a default
+ * makes the variable optional, so it is not reported), assignments earlier in the same command, or
+ * variables a sourced script exports. A false NEGATIVE there costs the old behaviour — the confusing
+ * path error — and a false positive would deny a hook that would have worked, so the parse errs
+ * toward silence and the check only ever ADDS a name to a failure that already happened.
+ */
+export declare function undefinedVariablesIn(command: string, supplied: Readonly<Record<string, string>>, env?: Readonly<Record<string, string | undefined>>): string[];

package/dist/internal/runtime/hooks/hooks-executor.d.ts

@@ -4,6 +4,15 @@ export interface HookCommand {
     matcher?: string;
     /** Optional timeout in ms; defaults to 30s. */
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookDecision {
     decision: "allow" | "deny" | "feedback";

package/dist/internal/runtime/hooks/hooks-source.d.ts

@@ -20,6 +20,15 @@ export interface HookCommand {
     command: string;
     matcher?: string;
     timeoutMs?: number;
+    /**
+     * The config file this command was declared in.
+     *
+     * Carried so the executor can supply the runtime contract the declaring DIALECT presumes — a
+     * command from `.claude/settings.json` is written against Claude Code's runtime and expects
+     * `$CLAUDE_PROJECT_DIR` to exist (#522). Absent for a command built in memory, which is native by
+     * construction.
+     */
+    sourcePath?: string;
 }
 export interface HookConfig {
     hooks?: Partial<Record<HookEvent, HookCommand[]>>;

package/dist/subagents-loader-UCNO7FUH.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var chunk43ZQRWAP_cjs = require('./chunk-43ZQRWAP.cjs');
+require('./chunk-AKJP2STZ.cjs');
+require('./chunk-4CLOXP6H.cjs');
+require('./chunk-4ZHTIJNE.cjs');
+require('./chunk-XL7Q7HB2.cjs');
+require('./chunk-EG4QM7ZJ.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunk43ZQRWAP_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-UCNO7FUH.cjs.map
+//# sourceMappingURL=subagents-loader-UCNO7FUH.cjs.map

package/dist/{subagents-loader-YEUFFPAL.cjs.map → subagents-loader-UCNO7FUH.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-YEUFFPAL.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-UCNO7FUH.cjs"}

package/dist/subagents-loader-XP5ERVDZ.js

@@ -0,0 +1,8 @@
+export { loadSubagents } from './chunk-LKBEROHN.js';
+import './chunk-247ZTLNU.js';
+import './chunk-LXQ6HKPS.js';
+import './chunk-ZZMZWBR6.js';
+import './chunk-D4CUGAKZ.js';
+import './chunk-XEQ3TM66.js';
+//# sourceMappingURL=subagents-loader-XP5ERVDZ.js.map
+//# sourceMappingURL=subagents-loader-XP5ERVDZ.js.map

package/dist/{subagents-loader-CRT5LLL3.js.map → subagents-loader-XP5ERVDZ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-CRT5LLL3.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-XP5ERVDZ.js"}

package/dist/subagents-loader.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkCQBXOJ6U_cjs = require('./chunk-CQBXOJ6U.cjs');
-require('./chunk-AQO3NSRG.cjs');
+var chunk43ZQRWAP_cjs = require('./chunk-43ZQRWAP.cjs');
+require('./chunk-AKJP2STZ.cjs');
 require('./chunk-4CLOXP6H.cjs');
 var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
 require('./chunk-XL7Q7HB2.cjs');
@@ -24,7 +24,7 @@ function resolveSources(options) {
 }
 async function discoverSubagents(cwd, options) {
   const sources = resolveSources(options);
-  return chunkCQBXOJ6U_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
+  return chunk43ZQRWAP_cjs.loadSubagents(cwd, sources.includes("project"), void 0);
 }
 async function loadSubagentDefinition(name, cwd, options) {
   return (await discoverSubagents(cwd, options))[name];

package/dist/subagents-loader.js

@@ -1,5 +1,5 @@
-import { loadSubagents } from './chunk-LXI4XZEC.js';
-import './chunk-UFLD2HEV.js';
+import { loadSubagents } from './chunk-LKBEROHN.js';
+import './chunk-247ZTLNU.js';
 import './chunk-LXQ6HKPS.js';
 import { ConfigurationError } from './chunk-ZZMZWBR6.js';
 import './chunk-D4CUGAKZ.js';

package/docs/error-codes.md

@@ -68,11 +68,11 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_invalid` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:116` |
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:39` |
-| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:429` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:234` |
-| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:152` +2 |
-| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:143` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:228` |
+| `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:433` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:265` |
+| `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:183` +2 |
+| `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:174` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:259` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:20` |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "4.63.3",
+  "version": "4.63.4",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",