pi-openappa 0.2.0 → 0.3.1

package/README.md

@@ -18,7 +18,8 @@ pi event ◀── enforce  ◀── decision  ◀─────────
   (the extension installs it automatically when missing) — version 0.31.x
   verified; see `docs/wire-notes.md` for the recorded contract
 - An APPA runtime listening on loopback (default `127.0.0.1:8787`)
-- A policy (`appa.toml`) that declares the tools your sessions may use
+- A policy (`appa.toml`) that declares the tools your sessions may use —
+  `/appa init` writes a starter one, or copy `templates/appa.toml`
 
 ## Install
 
@@ -61,10 +62,14 @@ empty content falls back to `APPA_CONFIG` or APPA's default:
   cd your-project && mkdir -p .pi && echo "appa.toml" > .pi/openappa
   ```
 
-A protected session brings the runtime up on its own: `session_start` invokes
-`appa hook --ensure-runtime`, passing `--config "$APPA_CONFIG"` when set and
-otherwise letting APPA use its own default policy (`~/.config/appa/appa.toml`).
-Protected sessions therefore need zero manual server management. A custom
+A protected session brings the runtime up on its own: `session_start` sends
+`appa hook --ensure-runtime` (passing `--config` when a policy is resolved),
+but **does not wait for it** — the boot runs on a serialized background lane,
+so a cold runtime, a first-run auto-install, or a slow start never sits in
+Pi's session-start path. Ordering is preserved: the SessionStart payload
+always lands before the first `PreToolUse`, and a runtime that cannot
+answer fails that first call closed with the reason (silence never means
+yes). A custom
 `APPA_RUNTIME_URL` names a runtime that is *yours* to start — the hook
 refuses with exactly that reason instead of guessing.
 
@@ -85,11 +90,12 @@ Opted-out sessions never invoke the hook.
 
 ## Configuration
 
-| Variable | Default | Meaning |
+| Source | Default | Meaning |
 |---|---|---|
 | `APPA_GATE` | unset | `1` forces protection on for this launch; `0` forces it off |
 | `.pi/openappa` | absent | Project marker: names that project's policy and forces protection on |
 | `.pi/no-openappa` | absent | Project opt-out: sessions started there run unguarded |
+| `~/.config/pi-openappa/settings.json` | absent | File settings: `config`, `runtimeUrl`, `hookBin`, `hookTimeoutMs`; env always wins, project markers beat `config` |
 | `APPA_RUNTIME_URL` | `http://127.0.0.1:8787` | Runtime endpoint (loopback only) |
 | `APPA_CONFIG` | unset | `appa.toml` the session auto-starts the runtime with |
 | `APPA_HOOK_BIN` | `appa` | Hook binary to invoke |
@@ -97,6 +103,58 @@ Opted-out sessions never invoke the hook.
 | `APPA_HOOK_TIMEOUT_MS` | `15000` | Kill the hook after this long; the call is then blocked |
 | `APPA_INSTALL_TIMEOUT_MS` | `120000` | Kill a stuck auto-install after this long |
 
+Policy resolution order: `APPA_CONFIG`, then the project marker's content,
+then `settings.json`'s `config`, then APPA's own default
+(`~/.config/appa/appa.toml`).
+
+## Starter policy: `/appa init`
+
+`templates/appa.toml` is a complete, self-contained policy written for Pi.
+It gates **flows, not tools**: sources mark data, sinks check it.
+
+| When a session carries… | it is refused at… |
+|---|---|
+| web text (`curl`/`wget`, `web_explore`, context7) | editing any existing file except docs/openspec/`*.md` (research lands in docs, it doesn't rewrite code); writing tests, devops (Makefile, justfile, scripts, CI, Dockerfile), infra (terraform, k8s, helm…), or credential-shaped paths; `git push` / `gh …`; `mem_save`/`mem_update` (poisoned memory must not persist) |
+| `.env`/credentials (read or commanded) | web tools (a secret-narrowed session cannot prove a query shareable) — trusted docs domains carved out for `curl`; bash output returns masked via `redact-secrets` |
+| anything | editing appa's own policy files |
+| nothing (clean session) | nowhere — reads, edits, tests, commits, pushes all flow |
+
+An undeclared tool is refused before it runs (deny-by-default; a `*`
+wildcard requires an annotator, so refusing is the only annotator-free
+stance — the commented `builtin = "llm"` block shows the classifier
+upgrade). Selectors use **Pi argument names** (`Read(path:…)`, not Claude
+Code's `file_path` — the stock battery's never match a Pi call), and the
+policy is **static rules only**: nothing host-coupled, nothing that can be
+unreachable. Taint lives in the trajectory label and only narrows — the
+manual reset is a **new session** (resume/fork inherit it; there is no
+`/untaint` by design).
+
+Install it one of three ways:
+
+```sh
+/appa init               # inside Pi: writes ~/.config/appa/appa.toml (+ settings.json)
+/appa init project       # writes ./appa.toml and the .pi/openappa marker
+cp templates/appa.toml ~/.config/appa/appa.toml   # from a checkout
+```
+
+`init` never clobbers: rerun with `--force` to overwrite. Subcommands
+autocomplete (`on`, `off`, `init`, `init project`, `status`).
+
+### Policy-as-code
+
+The policy is tested like code — no runtime needed, only the `appa` CLI:
+
+```sh
+just policy-check      # templates/appa.toml loads
+just policy-coverage   # every known Pi tool declared (Day E: refusals fail)
+just policy-test       # replay the usage-day traces (Days A–D, F)
+```
+
+`traces/*.appa` are line-based replays (`<canonical-tool> {` / one `arg:`
+JSON value per line / `}` / `expect allow|withhold|deny`); calls in one
+file share a trajectory, so taint accumulates exactly as live. All three
+gates run in `just check`.
+
 `/appa` reports protection, opt-out state, and runtime health; `/appa off`
 disables protection globally (marker `~/.config/pi-openappa/off`) and
 `/appa on` re-enables it, taking effect immediately including the

package/extensions/index.ts

@@ -3,12 +3,18 @@
  *
  * Thin by design: translate Pi events to `appa hook` invocations and enforce
  * the answer. No policy logic lives here; the APPA runtime owns every
- * decision. Protection is opt-in per session (APPA_GATE=1 at launch) and
- * fail-closed while gated: if the runtime cannot answer, the call is blocked.
+ * decision. Protection is ON by default (opt out with APPA_GATE=0, a project
+ * `.pi/no-openappa` marker, or `/appa off`) and fail-closed while gated: if
+ * the runtime cannot answer, the call is blocked. A missing `appa` binary
+ * self-installs once on the background lane; a first run with no policy
+ * anywhere and no runtime runs the session unprotected with one warning.
  *
  * Wire facts and constraints: docs/wire-notes.md
  */
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   parseCallDecision,
@@ -20,13 +26,16 @@ import {
   stopPayload,
   toolResponseFrom,
 } from "../src/adapter.ts";
-import { invokeAppaHook, resolveHookBin, type HookOutcome } from "../src/hook-client.ts";
+import { invokeAppaHook, resolveHookBin } from "../src/hook-client.ts";
+import type { InvokeOptions } from "../src/hook-client.ts";
 import { installAppa, type InstallOutcome } from "../src/installer.ts";
 import {
+  appaDefaultConfigPath,
   appaDefaultPolicyExists,
   captureGate,
   checkHealth,
   setGloballyOff,
+  settingsPath,
   type GateState,
 } from "../src/gate.ts";
 
@@ -35,6 +44,14 @@ interface TextPart {
   text: string;
 }
 
+/** The starter policy `/appa init` writes (templates/appa.toml in this package). */
+function templateToml(): string {
+  return readFileSync(
+    fileURLToPath(new URL("../templates/appa.toml", import.meta.url)),
+    "utf8",
+  );
+}
+
 export default function (pi: ExtensionAPI): void {
   /** Launch-fixed protection state; null until the session starts. */
   let gate: GateState | null = null;
@@ -48,101 +65,137 @@ export default function (pi: ExtensionAPI): void {
    */
   const pendingInputs = new Map<string, Record<string, unknown>>();
 
+  /**
+   * Serialized hook lane. Every `appa hook` invocation for this session runs
+   * through here in order, so the SessionStart payload (with
+   * `--ensure-runtime`) always lands before the first PreToolUse even though
+   * session_start does not wait for it. Startup stays off the fast-start
+   * lane: the runtime boot — and a first run's auto-install — is paid by
+   * whichever tool call needs the runtime first, and a runtime that cannot
+   * answer fails that call closed with the reason — never a slower session
+   * start.
+   */
+  let lane: Promise<unknown> = Promise.resolve();
+  const enqueue = <T>(run: () => Promise<T>): Promise<T> => {
+    const outcome = lane.then(run, run);
+    lane = outcome.then(
+      () => undefined,
+      () => undefined,
+    );
+    return outcome;
+  };
+
   const gated = (): boolean => gate?.gated === true && !unprotected;
 
+  const hookOptions = (state: GateState, extra: InvokeOptions = {}): InvokeOptions => {
+    const options: InvokeOptions = { ...extra };
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    return options;
+  };
+
   pi.on("session_start", async (event, ctx) => {
     gate = captureGate(process.env, ctx.cwd);
     sessionId = ctx.sessionManager.getSessionId();
     if (!gate.gated) return;
     unprotected = false;
-
-    const payload = sessionStartPayload(sessionId, event.reason, ctx.cwd);
-    const options = {
-      ensureRuntime: true,
-      ...(gate.config !== undefined ? { config: gate.config } : {}),
-    };
-    const notify = (message: string, kind: "info" | "warning"): void => {
-      if (ctx.hasUI) ctx.ui.notify(message, kind);
-    };
-    let outcome = await invokeAppaHook(payload, options);
-    let warnedAlready = false;
-    // A missing default `appa` is self-provisioned: run the official install
-    // script once, then retry bringing the runtime up. Custom APPA_HOOK_BINs
-    // are the user's own and never auto-installed.
-    if (outcome.binaryMissing && resolveHookBin(process.env) === "appa") {
-      notify(
-        "`appa` was not found — installing the OpenAPPA runtime " +
-          "(https://openappa.com/install.sh)…",
-        "info",
-      );
-      const install = await installAppa();
-      if (install.exitCode !== 0) {
-        warnedAlready = true;
+    const state = gate;
+    const options: InvokeOptions = { ensureRuntime: true };
+    if (state.config !== undefined) options.config = state.config;
+    if (state.hookTimeoutMs !== undefined) options.timeoutMs = state.hookTimeoutMs;
+    // Backgrounded on purpose (see `lane`): a cold runtime boot — or a first
+    // run that still has to install the runtime — must not sit in Pi's
+    // session-start path. Auto-install, the retry, and the first-run
+    // unprotected decision all run serialized on the lane; failure surfaces
+    // as a warning when it settles.
+    void enqueue(async () => {
+      const notify = (message: string, kind: "info" | "warning"): void => {
+        if (ctx.hasUI) ctx.ui.notify(message, kind);
+      };
+      const payload = sessionStartPayload(sessionId, event.reason, ctx.cwd);
+      let outcome = await invokeAppaHook(payload, options);
+      let warnedAlready = false;
+      // A missing default `appa` is self-provisioned: run the official install
+      // script once, then retry bringing the runtime up. Custom APPA_HOOK_BINs
+      // are the user's own and never auto-installed.
+      if (outcome.binaryMissing && resolveHookBin(process.env) === "appa") {
         notify(
-          `OpenAPPA auto-install failed: ${outcomeTail(install)}. ` +
-            "Tool calls stay blocked; install `appa` manually (see the README) or run /appa off.",
-          "warning",
+          "`appa` was not found — installing the OpenAPPA runtime " +
+            "(https://openappa.com/install.sh)…",
+          "info",
         );
-      } else {
-        const retry = await invokeAppaHook(payload, options);
-        if (retry.binaryMissing) {
+        const install = await installAppa();
+        if (install.exitCode !== 0) {
           warnedAlready = true;
           notify(
-            "OpenAPPA auto-install finished but `appa` is still not on PATH. " +
-              `Installer output: ${outcomeTail(install)} — restart the session once PATH has it.`,
+            `OpenAPPA auto-install failed: ${outcomeTail(install)}. ` +
+              "Tool calls stay blocked; install `appa` manually (see the README) or run /appa off.",
             "warning",
           );
+        } else {
+          const retry = await invokeAppaHook(payload, options);
+          if (retry.binaryMissing) {
+            warnedAlready = true;
+            notify(
+              "OpenAPPA auto-install finished but `appa` is still not on PATH. " +
+                `Installer output: ${outcomeTail(install)} — restart the session once PATH has it.`,
+              "warning",
+            );
+          }
+          outcome = retry;
         }
-        outcome = retry;
       }
-    }
-    if (outcome.exitCode !== 0) {
-      // No policy anywhere and nothing answering: run this session
-      // unprotected with one warning instead of fail-closed (the configured
-      // default). A named policy that fails stays fail-closed below.
-      if (
-        resolveHookBin(process.env) === "appa" &&
-        gate.config === undefined &&
-        !appaDefaultPolicyExists(process.env) &&
-        !(await checkHealth(gate.runtimeUrl)).ok
-      ) {
-        unprotected = true;
-        if (!warnedAlready) {
-          notify(
-            "OpenAPPA is on by default, but no policy exists (APPA_CONFIG, " +
-              ".pi/openappa, or ~/.config/appa/appa.toml) and no runtime answers " +
-              `at ${gate.runtimeUrl} — this session runs unprotected. ` +
-              "Write a policy, or run /appa off.",
+      if (outcome.exitCode !== 0) {
+        // No policy anywhere and nothing answering: run this session
+        // unprotected with one warning instead of fail-closed (the configured
+        // default). A named policy that fails stays fail-closed below.
+        if (
+          resolveHookBin(process.env) === "appa" &&
+          state.config === undefined &&
+          !appaDefaultPolicyExists(process.env) &&
+          !(await checkHealth(state.runtimeUrl)).ok
+        ) {
+          unprotected = true;
+          if (!warnedAlready) {
+            notify(
+              "OpenAPPA is on by default, but no policy exists (run /appa init, " +
+                "or set APPA_CONFIG, .pi/openappa, or ~/.config/appa/appa.toml) and no runtime answers " +
+                `at ${state.runtimeUrl} — this session runs unprotected. ` +
+                "Write a policy, or run /appa off.",
+              "warning",
+            );
+          }
+          return;
+        }
+        if (ctx.hasUI && !warnedAlready) {
+          const remedy =
+            state.config === undefined
+              ? " Provide a policy (this project's .pi/openappa, /appa init, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
+              : "";
+          ctx.ui.notify(
+            `OpenAPPA gated but the runtime did not answer (${state.runtimeUrl}): ` +
+              `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
+              "Tool calls will be blocked until it answers.",
             "warning",
           );
         }
-        return;
-      }
-      if (ctx.hasUI && !warnedAlready) {
-      const remedy =
-        gate.config === undefined
-          ? " Provide a policy (this project's .pi/openappa, APPA_CONFIG, or ~/.config/appa/appa.toml), or run /appa off."
-          : "";
-      ctx.ui.notify(
-        `OpenAPPA gated but the runtime did not answer (${gate.runtimeUrl}): ` +
-          `${outcome.stderr.trim() || `exit ${outcome.exitCode}`}.${remedy} ` +
-          "Tool calls will be blocked until it answers.",
-        "warning",
-      );
       }
-    }
+    });
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
     if (!gated()) return;
     // The prompt event establishes the turn boundary; it does not gate.
-    await invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd));
+    await enqueue(() =>
+      invokeAppaHook(promptPayload(sessionId, event.prompt, ctx.cwd), hookOptions(gate!)),
+    );
   });
 
   pi.on("tool_call", async (event, ctx) => {
     if (!gated()) return;
     const payload = preToolUsePayload(sessionId, event.toolName, event.input, ctx.cwd);
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseCallDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "deny") {
       return { block: true, reason: `appa: ${decision.reason}` };
@@ -167,7 +220,9 @@ export default function (pi: ExtensionAPI): void {
       response,
       ctx.cwd,
     );
-    const outcome = await invokeAppaHook(payload);
+    const outcome = await enqueue(() =>
+      invokeAppaHook(payload, hookOptions(gate!)),
+    );
     const decision = parseResultDecision(outcome.exitCode, outcome.stdout, outcome.stderr);
     if (decision.type === "pass") {
       return undefined;
@@ -181,7 +236,9 @@ export default function (pi: ExtensionAPI): void {
   pi.on("turn_end", async () => {
     if (!gated()) return;
     // Turn completion is reported, never gated (matching --turn-end).
-    await invokeAppaHook(stopPayload(sessionId), { turnEnd: true });
+    await enqueue(() =>
+      invokeAppaHook(stopPayload(sessionId), hookOptions(gate!, { turnEnd: true })),
+    );
   });
 
   pi.on("session_shutdown", () => {
@@ -189,9 +246,36 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("appa", {
-    description: "Show OpenAPPA status; `appa on|off` toggles protection globally",
+    description:
+      "OpenAPPA guard: status, `appa on|off` global toggle, `appa init [project]` writes a starter policy",
+    getArgumentCompletions: (argumentPrefix) => {
+      const items = [
+        {
+          value: "on",
+          label: "on",
+          description: "Re-enable default-on protection for every session",
+        },
+        { value: "off", label: "off", description: "Disable protection globally (/appa on re-enables)" },
+        {
+          value: "init",
+          label: "init",
+          description: "Write the starter policy to ~/.config/appa/appa.toml",
+        },
+        {
+          value: "init project",
+          label: "init project",
+          description: "Write ./appa.toml plus the .pi/openappa project marker",
+        },
+        { value: "status", label: "status", description: "Show protection and runtime health" },
+      ];
+      const prefix = argumentPrefix.trim();
+      const hits = prefix === "" ? items : items.filter((item) => item.value.startsWith(prefix));
+      return hits.length > 0 ? hits : null;
+    },
     handler: async (args, ctx) => {
-      const arg = args.trim();
+      const tokens = args.trim().split(/\s+/).filter((token) => token !== "");
+      const arg = tokens[0] ?? "";
+
       if (arg === "on" || arg === "off") {
         setGloballyOff(process.env, arg === "off");
         gate = captureGate(process.env, ctx.cwd);
@@ -205,6 +289,14 @@ export default function (pi: ExtensionAPI): void {
         }
         return;
       }
+
+      if (arg === "init") {
+        const scope = tokens[1] === "project" ? "project" : "user";
+        const force = tokens.includes("--force");
+        await runInit(scope, force, ctx);
+        return;
+      }
+
       const state = gate ?? captureGate(process.env, ctx.cwd);
       const mode =
         state.source === "project"
@@ -237,6 +329,59 @@ export default function (pi: ExtensionAPI): void {
       }
     },
   });
+
+  /** `/appa init` — write the starter policy (and settings) without clobbering. */
+  async function runInit(
+    scope: "user" | "project",
+    force: boolean,
+    ctx: { cwd: string; hasUI: boolean; ui: { notify: (message: string, type?: "info" | "warning" | "error") => void } },
+  ): Promise<void> {
+    const notify = (message: string, type: "info" | "warning" | "error" = "info") => {
+      if (ctx.hasUI) ctx.ui.notify(message, type);
+    };
+    try {
+      if (scope === "project") {
+        const policy = join(ctx.cwd, "appa.toml");
+        const marker = join(ctx.cwd, ".pi", "openappa");
+        if (existsSync(policy) && !force) {
+          notify(`${policy} already exists; rerun with --force to overwrite it.`, "warning");
+          return;
+        }
+        mkdirSync(dirname(policy), { recursive: true });
+        writeFileSync(policy, templateToml());
+        if (!existsSync(marker)) {
+          mkdirSync(dirname(marker), { recursive: true });
+          writeFileSync(marker, "appa.toml\n");
+        }
+        notify(
+          `Wrote ${policy} and the .pi/openappa marker. Sessions started in this directory are protected; new sessions pick the policy up (trajectories keep the policy they opened with).`,
+        );
+        return;
+      }
+      const policy = appaDefaultConfigPath(process.env);
+      if (existsSync(policy) && !force) {
+        notify(
+          `${policy} already exists; rerun with --force to overwrite it, or /appa init project for one project.`,
+          "warning",
+        );
+        return;
+      }
+      mkdirSync(dirname(policy), { recursive: true });
+      writeFileSync(policy, templateToml());
+      const settings = settingsPath(process.env);
+      const lines: string[] = [`Wrote the starter policy to ${policy}.`];
+      if (!existsSync(settings)) {
+        mkdirSync(dirname(settings), { recursive: true });
+        writeFileSync(settings, `${JSON.stringify({ config: policy }, null, 2)}\n`);
+        lines.push(`Wrote ${settings} pointing at it.`);
+      }
+      lines.push("Protection is on by default; /appa off disables it, /appa init project scopes a policy to one project.");
+      notify(lines.join(" "));
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      notify(`/appa init failed: ${detail}`, "error");
+    }
+  }
 }
 
 /** Last ~200 chars of installer output, whitespace-normalized, for notices. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-openappa",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Thin OpenAPPA guard extension for Pi: gates tool calls through the APPA runtime. No policy logic lives here.",
   "keywords": [
     "pi-package",
@@ -19,6 +19,13 @@
   "homepage": "https://github.com/aemonge-dev/pi-openappa#readme",
   "bugs": "https://github.com/aemonge-dev/pi-openappa/issues",
   "type": "module",
+  "files": [
+    "extensions/",
+    "src/",
+    "templates/",
+    "traces/",
+    "docs/"
+  ],
   "pi": {
     "extensions": ["./extensions/index.ts"]
   },

package/src/gate.ts

@@ -10,7 +10,8 @@
  * Otherwise the session is protected (the default).
  *
  * An explicit APPA_CONFIG always wins as the policy source; otherwise a
- * project marker's content is used; otherwise APPA's own default. The gate is
+ * project marker's content is used; otherwise the settings file's `config`;
+ * otherwise APPA's own default. The gate is
  * captured once per session so a session cannot disable its own protection
  * mid-run; `/appa on|off` are deliberate user commands and do re-resolve.
  * The legacy `always-on` marker from opt-in days is ignored; `/appa on`
@@ -39,6 +40,55 @@ export function legacyAlwaysOnMarkerPath(env: NodeJS.ProcessEnv): string {
   return join(baseConfigDir(env), "pi-openappa", "always-on");
 }
 
+/** The policy a gated session auto-starts the runtime with, by APPA default. */
+export function appaDefaultConfigPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "appa", "appa.toml");
+}
+
+/** File-backed settings for this extension (see `ExtensionSettings`). */
+export function settingsPath(env: NodeJS.ProcessEnv): string {
+  return join(baseConfigDir(env), "pi-openappa", "settings.json");
+}
+
+/**
+ * Keys read from `settings.json`. Every key is optional; environment
+ * variables of the same meaning always win over the file, and the file
+ * always wins over the built-in defaults. Written by `/appa init`.
+ */
+export interface ExtensionSettings {
+  /** Policy path passed as `--config` (the APPA_CONFIG fallback). */
+  config?: string;
+  /** Runtime endpoint (the APPA_RUNTIME_URL fallback). */
+  runtimeUrl?: string;
+  /** Hook binary (the APPA_HOOK_BIN fallback). */
+  hookBin?: string;
+  /** Hook timeout in ms (the APPA_HOOK_TIMEOUT_MS fallback). */
+  hookTimeoutMs?: number;
+}
+
+/** Read settings.json; a missing or malformed file resolves to `{}`. */
+export function readSettings(env: NodeJS.ProcessEnv): ExtensionSettings {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(settingsPath(env), "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return {};
+    }
+    const out: ExtensionSettings = {};
+    const record = parsed as Record<string, unknown>;
+    for (const key of ["config", "runtimeUrl", "hookBin"] as const) {
+      const value = record[key];
+      if (typeof value === "string" && value !== "") out[key] = value;
+    }
+    const timeout = record["hookTimeoutMs"];
+    if (typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0) {
+      out.hookTimeoutMs = timeout;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
 export function projectMarkerPath(cwd: string): string {
   return join(cwd, ".pi", "openappa");
 }
@@ -88,12 +138,14 @@ export interface GateState {
   gated: boolean;
   /** Most specific reason this session is (or is not) protected. */
   source: GateSource;
-  /** Policy for auto-start: explicit env wins, then project marker content. */
+  /** Policy for auto-start: env, then project marker, then settings file. */
   config?: string;
   /** Runtime URL for health reporting (the hook binary reads it from env). */
   runtimeUrl: string;
   /** Hook binary used for reporting. */
   hookBin: string;
+  /** Hook timeout in ms when settings pin one; otherwise the default applies. */
+  hookTimeoutMs?: number;
 }
 
 /** Read a project marker's optional policy path; empty content resolves to none. */
@@ -108,9 +160,11 @@ function projectConfig(cwd: string): string | undefined {
 }
 
 export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
+  const settings = readSettings(env);
   const base = {
-    runtimeUrl: env.APPA_RUNTIME_URL ?? DEFAULT_RUNTIME_URL,
-    hookBin: env.APPA_HOOK_BIN ?? "appa",
+    runtimeUrl: env.APPA_RUNTIME_URL ?? settings.runtimeUrl ?? DEFAULT_RUNTIME_URL,
+    hookBin: env.APPA_HOOK_BIN ?? settings.hookBin ?? "appa",
+    ...(settings.hookTimeoutMs !== undefined ? { hookTimeoutMs: settings.hookTimeoutMs } : {}),
   };
   const explicitConfig =
     env.APPA_CONFIG !== undefined && env.APPA_CONFIG !== ""
@@ -120,10 +174,12 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
   const projectOff = cwd !== undefined && existsSync(projectNoMarkerPath(cwd));
   const projectCfg =
     projectGated && cwd !== undefined ? projectConfig(cwd) : undefined;
+  // Precedence: launch env, then the project marker (per-project intent),
+  // then the global settings file (see readSettings).
+  const config = explicitConfig ?? projectCfg ?? settings.config;
 
   // An explicit launch choice beats every marker.
   if (env.APPA_GATE === "1") {
-    const config = explicitConfig ?? projectCfg;
     return {
       gated: true,
       source: "env-on",
@@ -139,7 +195,6 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
     return { gated: false, source: "project-off", ...base };
   }
   if (projectGated) {
-    const config = explicitConfig ?? projectCfg;
     return {
       gated: true,
       source: "project",
@@ -155,7 +210,7 @@ export function captureGate(env: NodeJS.ProcessEnv, cwd?: string): GateState {
     gated: true,
     source: "default",
     ...base,
-    ...(explicitConfig !== undefined ? { config: explicitConfig } : {}),
+    ...(config !== undefined ? { config } : {}),
   };
 }