okstra 0.13.2 → 0.14.1

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, 9개 render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: `Claude lead` + `Claude worker` · `Codex worker` · `Gemini worker` · `Report writer worker`의 필수 구성과 Agent Teams 우선 시도를 강제합니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 만 `.project-docs/okstra/` 아래 저장됩니다 — 사용자의 `~/.claude/settings.json` 이나 프로젝트 `.claude/settings.local.json` 은 건드리지 않으며, per-session permission 은 `claude --settings` 로 런타임 주입합니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.project-docs/okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않으며 별도 `--settings` CLI 주입도 필요 없습니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Optional integrations**: worker error sidecar, token usage / cost accounting을 옵션으로 제공합니다.
 
@@ -213,7 +213,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 **Mode A — `okstra.sh` 가 새 claude 프로세스를 띄움**
 - `--render-only`를 사용하면 Claude를 실행하지 않고 instruction-set 만 만든 뒤 종료합니다.
 - `--render-only`가 없으면 prepare 단계가 Claude session ID 를 선할당하고 current run 의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh` 를 생성합니다.
-- 이후 대상 프로젝트 루트에서 resolved `Claude lead` model execution value 로 `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" --settings <runtime-settings> "$PROMPT"` 를 `exec` 합니다.
+- 이후 대상 프로젝트 루트에서 resolved `Claude lead` model execution value 로 `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` 를 `exec` 합니다. (이전 버전의 `--settings <runtime-settings>` 인자는 0.14.0 부터 제거됨 — 권한은 `<PROJECT_ROOT>/.claude/settings.local.json` symlink 가 담당.)
 - `okstra.sh` 는 handoff 까지만 수행하고, 최종 보고서 저장과 run/task 상태 갱신은 Claude lead 가 이어서 수행합니다.
 
 **Mode B — `okstra-run` skill 이 현재 claude 세션 안에서 인계**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.13.2",
+  "version": "0.14.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.13.2",
-  "builtAt": "2026-05-13T02:07:39.150Z",
+  "package": "0.14.1",
+  "builtAt": "2026-05-13T03:17:50.448Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/codex-worker.md

@@ -18,7 +18,7 @@ description: |
   </example>
 model: inherit
 color: cyan
-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
 You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and return the analysis result.
@@ -27,12 +27,14 @@ You are a Codex worker agent. Your job is to execute the OpenAI Codex CLI and re
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+$HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
 ```
 
+The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper forwards it to codex as `--add-dir`, which grants the codex sandbox write access to the worktree (where all implementation-phase mutations occur). Without it, codex's `workspace-write` sandbox is anchored only at `<project-root>` and rejects every Edit/Write that targets the worktree (EPERM), which is the failure pattern that originally motivated this argument.
+
 The wrapper internally runs:
 ```bash
-codex exec -C "<project-root>" --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
+codex exec -C "<project-root>" [--add-dir "<worktree-path>"] --model "<model>" --sandbox workspace-write - < "<prompt-path>" 2>/dev/null
 ```
 
 The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `codex exec ... - < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(codex exec:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`.
@@ -67,20 +69,34 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    - If neither is available, immediately return `CODEX_MODEL_MISSING: assigned Codex model execution value was not provided`. Do NOT fall back to training-data defaults — historical codex defaults like `o4-mini` are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `CODEX_MODEL_MISSING` rather than guessing.
 
-7. If installed, execute the prompt through the wrapper as a single command with a Bash timeout of 120000 ms. Pass the three positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`:
+7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Codex runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
+
+   **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+   $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
    ```
-   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-C`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. Omitting it during implementation will cause every Edit/Write to fail with EPERM. The wrapper handles `-C`, `--add-dir`, `--model`, `--sandbox workspace-write`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `codex exec` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(codex exec:*)` and produce a permission prompt every dispatch.
+
+   **Poll loop (60-second cadence, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time.
+   - Repeat:
+     1. Foreground `Bash` call: `sleep 60` (or shorter on the first iteration if you expect a fast finish).
+     2. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`.
+     3. If `status == "completed"`: break out of the loop and proceed to step 8.
+     4. If `now - start_ts > 1800` seconds: call `KillShell(shell_id: <shell_id>)`, then record a `cli-failure` event with `--error-type cli-failure`, `--exit-code 124`, `--duration-ms 1800000`, `--message "okstra-codex-exec.sh exceeded 30m polling cap"`, and return `CODEX_CLI_TIMEOUT: codex exec exceeded 30-minute polling cap`.
+     5. Otherwise continue polling.
+   - Do NOT abort the loop on transient `running` status. Only `completed` or the 30-minute cap end it.
+   - Do NOT issue parallel `BashOutput` calls or speculate about progress between polls.
 
-8. Return the codex output as-is without modification.
+8. Concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification. If the final `BashOutput` reports a non-zero `exit_code`, follow the **CLI failure** rule in §"Error reporting" before returning.
 
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Codex CLI (via `okstra-codex-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
 
-- Return immediately after the wrapper script call returns (or after recording any required `cli-failure` event for a non-zero exit / timeout / rate-limit).
-- Do NOT perform additional `Read`, `Grep`, `Glob`, or other tool calls before or after the CLI dispatch beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
+- Return immediately after the polling loop exits with `completed` (or after recording any required `cli-failure` event for a non-zero exit / 30-minute cap / rate-limit).
+- The only tool calls permitted during the polling loop are `Bash` (for `sleep`), `BashOutput`, and — on the timeout path only — `KillShell`. Do NOT perform additional `Read`, `Grep`, `Glob` calls between polls; do NOT inspect intermediate wrapper output mid-run.
+- Outside the polling loop, no `Read`, `Grep`, or `Glob` beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
 - Do NOT re-invoke `okstra-codex-exec.sh` to "double-check" or "rerun for safety" — convergence (Phase 5.5) handles cross-worker reconciliation. A single CLI dispatch per dispatched-prompt is the contract.
 
 The Codex CLI's own exit terminates the underlying analysis; this wrapper terminates by returning its captured output (or sentinel).
@@ -96,9 +112,9 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Cod
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Codex model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to codex after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
-- For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three positional args:
+- For long prompts, the wrapper script reads from the saved project-local prompt history file via stdin redirect internally. The caller invokes the wrapper with three required positional args + the worktree path for implementation phase:
   ```bash
-  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>"
+  $HOME/.okstra/bin/okstra-codex-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -146,9 +162,12 @@ two kinds of errors via `scripts/okstra-error-log.py`:
    then append. Lead will dump it to the run error log after this subagent
    terminates.
 
-2. **CLI failure (lead-observed)** — if `codex exec` returns non-zero, times
-   out (Bash 120000ms), or returns a rate-limit/auth message, immediately
-   append a `cli-failure` event directly to the run error log:
+2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
+   reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
+   captured stdout/stderr carries a rate-limit/auth message, immediately
+   append a `cli-failure` event directly to the run error log. The
+   30-minute-cap path additionally requires a prior `KillShell` call against
+   the dispatched `bash_id`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
@@ -158,7 +177,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --agent codex-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path>" \
+     --command "$HOME/.okstra/bin/okstra-codex-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

package/runtime/agents/workers/gemini-worker.md

@@ -18,7 +18,7 @@ description: |
   </example>
 model: inherit
 color: green
-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+tools: ["Bash", "BashOutput", "KillShell", "Read", "Write", "Glob", "Grep"]
 ---
 
 You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and return the analysis result.
@@ -27,12 +27,14 @@ You are a Gemini worker agent. Your job is to execute the Google Gemini CLI and
 
 **Required form (uses the okstra wrapper to avoid redirect-triggered permission prompts):**
 ```bash
-$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+$HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" [<absolute-worktree-path>]
 ```
 
+The fourth argument is **mandatory for implementation phase** and optional otherwise. It must be the literal `EXECUTOR_WORKTREE_PATH` recorded in the run context; the wrapper appends it to gemini's `--include-directories` list so the model can both read and operate on the worktree alongside project-root.
+
 The wrapper internally runs:
 ```bash
-gemini -p - -m "<model>" -o text --include-directories "<project-root>" < "<prompt-path>" 2>/dev/null
+gemini -p - -m "<model>" -o text --include-directories "<project-root>[,<worktree-path>]" < "<prompt-path>" 2>/dev/null
 ```
 
 The wrapper exists because Claude Code's Bash permission matcher rejects simple-prefix matches when the command contains stdin/stderr redirects. Calling `gemini -p - ... < <path> 2>/dev/null` directly triggers a permission prompt every dispatch even when `Bash(gemini:*)` is allowlisted. The wrapper folds the redirects inside, so the harness sees a single non-redirect command that matches `Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)`.
@@ -67,20 +69,34 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    - If no assigned model execution value can be determined, immediately return `GEMINI_MODEL_MISSING: assigned Gemini model execution value was not provided`. Do NOT fall back to training-data defaults — historical Gemini defaults (e.g. `gemini-1.5-flash`) are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `GEMINI_MODEL_MISSING` rather than guessing.
 
-7. If installed, execute the prompt through the wrapper as a single command with a Bash timeout of 120000 ms. Pass the three positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`:
+7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Gemini runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
+
+   **Dispatch (background, no foreground timeout):**
    ```bash
-   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>"
+   $HOME/.okstra/bin/okstra-gemini-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-path>" "<absolute-worktree-path>"
    ```
-   Substitute the literal extracted Project Root, model execution value, and prompt-history path in place of the placeholders above. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
+   Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
+
+   **Poll loop (60-second cadence, 30-minute hard cap):**
+   - Record `start_ts` at dispatch time.
+   - Repeat:
+     1. Foreground `Bash` call: `sleep 60` (or shorter on the first iteration if you expect a fast finish).
+     2. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`.
+     3. If `status == "completed"`: break out of the loop and proceed to step 8.
+     4. If `now - start_ts > 1800` seconds: call `KillShell(shell_id: <shell_id>)`, then record a `cli-failure` event with `--error-type cli-failure`, `--exit-code 124`, `--duration-ms 1800000`, `--message "okstra-gemini-exec.sh exceeded 30m polling cap"`, and return `GEMINI_CLI_TIMEOUT: gemini exec exceeded 30-minute polling cap`.
+     5. Otherwise continue polling.
+   - Do NOT abort the loop on transient `running` status. Only `completed` or the 30-minute cap end it.
+   - Do NOT issue parallel `BashOutput` calls or speculate about progress between polls.
 
-8. Return the gemini output as-is without modification.
+8. Concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification. If the final `BashOutput` reports a non-zero `exit_code`, follow the **CLI failure** rule in §"Error reporting" before returning.
 
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Gemini CLI (via `okstra-gemini-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
 
-- Return immediately after the wrapper script call returns (or after recording any required `cli-failure` event for a non-zero exit / timeout / rate-limit).
-- Do NOT perform additional `Read`, `Grep`, `Glob`, or other tool calls before or after the CLI dispatch beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
+- Return immediately after the polling loop exits with `completed` (or after recording any required `cli-failure` event for a non-zero exit / 30-minute cap / rate-limit).
+- The only tool calls permitted during the polling loop are `Bash` (for `sleep`), `BashOutput`, and — on the timeout path only — `KillShell`. Do NOT perform additional `Read`, `Grep`, `Glob` calls between polls; do NOT inspect intermediate wrapper output mid-run.
+- Outside the polling loop, no `Read`, `Grep`, or `Glob` beyond what is strictly required by steps 1–7 (prompt persistence, Project Root extraction, model resolution).
 - Do NOT re-invoke `okstra-gemini-exec.sh` to "double-check" or "rerun for safety" — convergence (Phase 5.5) handles cross-worker reconciliation. A single CLI dispatch per dispatched-prompt is the contract.
 
 The Gemini CLI's own exit terminates the underlying analysis; this wrapper terminates by returning its captured output (or sentinel).
@@ -96,9 +112,9 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Gemini model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to gemini after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
-- For long prompts, dispatch through the wrapper with literal absolute paths:
+- For long prompts, dispatch through the wrapper with literal absolute paths (plus the worktree path for implementation phase):
   ```bash
-  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>"
+  $HOME/.okstra/bin/okstra-gemini-exec.sh "<literal-project-root>" "<assigned-model-execution-value>" "<literal-prompt-history-path>" "<literal-worktree-path>"
   ```
 - If the parent directory does not exist yet, create it before writing the prompt file.
 
@@ -146,9 +162,12 @@ two kinds of errors via `scripts/okstra-error-log.py`:
    then append. Lead will dump it to the run error log after this subagent
    terminates.
 
-2. **CLI failure (lead-observed)** — if `gemini` returns non-zero, times out
-   (Bash 120000ms), or returns a rate-limit/auth message, immediately append
-   a `cli-failure` event directly to the run error log:
+2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
+   reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
+   captured stdout/stderr carries a rate-limit/auth message, immediately
+   append a `cli-failure` event directly to the run error log. The
+   30-minute-cap path additionally requires a prior `KillShell` call against
+   the dispatched `bash_id`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
@@ -158,7 +177,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --agent gemini-worker --agent-role worker \
      --model "<assigned-model-execution-value>" \
      --error-type cli-failure \
-     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path>" \
+     --command "$HOME/.okstra/bin/okstra-gemini-exec.sh <project-root> <m> <prompt-path> <worktree-path>" \
      --command-kind cli-invoke \
      --exit-code <N> --duration-ms <ms> \
      --message "<one-line summary>" \

package/runtime/bin/okstra-codex-exec.sh

@@ -13,20 +13,29 @@
 #   Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)
 #
 # Usage:
-#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path>
+#   okstra-codex-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
 #
-# All three arguments are required and must be absolute paths or literal model
-# strings. The wrapper exits non-zero on any preflight failure.
+# project-root / model-execution-value / prompt-path are required.
+#
+# worktree-path is optional and used for okstra implementation phase, where the
+# executor must mutate files inside a git worktree that lives outside
+# project-root. When supplied (non-empty), it is forwarded to codex as
+# `--add-dir <worktree-path>` so the codex sandbox grants write access to that
+# directory alongside the primary workspace anchored at project-root. When
+# omitted or empty, no `--add-dir` is added (existing analysis-phase behavior).
+#
+# The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -ne 3 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 4 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
 project_root="$1"
 model="$2"
 prompt_path="$3"
+worktree_path="${4-}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-codex-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -48,6 +57,16 @@ if ! command -v codex >/dev/null 2>&1; then
   exit 127
 fi
 
+if [[ -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  printf 'okstra-codex-exec: worktree-path was provided but is not a directory: %q\n' "$worktree_path" >&2
+  exit 68
+fi
+
+extra_args=()
+if [[ -n "$worktree_path" ]]; then
+  extra_args+=(--add-dir "$worktree_path")
+fi
+
 # stdin redirect and stderr suppression are intentionally inside the wrapper —
 # this is the entire reason this script exists.
-exec codex exec -C "$project_root" --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null
+exec codex exec -C "$project_root" ${extra_args[@]+"${extra_args[@]}"} --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra-gemini-exec.sh

@@ -13,20 +13,29 @@
 #   Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)
 #
 # Usage:
-#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path>
+#   okstra-gemini-exec.sh <project-root> <model-execution-value> <prompt-path> [worktree-path]
 #
-# All three arguments are required and must be absolute paths or literal model
-# strings. The wrapper exits non-zero on any preflight failure.
+# project-root / model-execution-value / prompt-path are required.
+#
+# worktree-path is optional and used for okstra implementation phase, where the
+# executor must mutate files inside a git worktree that lives outside
+# project-root. When supplied (non-empty), it is appended to gemini's
+# `--include-directories` list (comma-separated) so the model can see and
+# operate on the worktree alongside the primary workspace. When omitted or
+# empty, only project-root is included (existing analysis-phase behavior).
+#
+# The wrapper exits non-zero on any preflight failure.
 set -euo pipefail
 
-if [[ $# -ne 3 ]]; then
-  printf 'usage: %s <project-root> <model-execution-value> <prompt-path>\n' "$(basename "$0")" >&2
+if [[ $# -lt 3 || $# -gt 4 ]]; then
+  printf 'usage: %s <project-root> <model-execution-value> <prompt-path> [worktree-path]\n' "$(basename "$0")" >&2
   exit 64
 fi
 
 project_root="$1"
 model="$2"
 prompt_path="$3"
+worktree_path="${4-}"
 
 if [[ -z "$project_root" || ! -d "$project_root" ]]; then
   printf 'okstra-gemini-exec: project-root is missing or not a directory: %q\n' "$project_root" >&2
@@ -48,8 +57,18 @@ if ! command -v gemini >/dev/null 2>&1; then
   exit 127
 fi
 
+if [[ -n "$worktree_path" && ! -d "$worktree_path" ]]; then
+  printf 'okstra-gemini-exec: worktree-path was provided but is not a directory: %q\n' "$worktree_path" >&2
+  exit 68
+fi
+
+include_dirs="$project_root"
+if [[ -n "$worktree_path" ]]; then
+  include_dirs="$project_root,$worktree_path"
+fi
+
 # stdin redirect and stderr suppression are intentionally inside the wrapper —
 # this is the entire reason this script exists. Gemini CLI has no `--cd` flag,
 # so workspace correctness is anchored via `--include-directories` plus the
 # Project Root referenced in the prompt body itself.
-exec gemini -p - -m "$model" -o text --include-directories "$project_root" < "$prompt_path" 2>/dev/null
+exec gemini -p - -m "$model" -o text --include-directories "$include_dirs" < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra.sh

@@ -152,17 +152,20 @@ if [[ -z "$LAUNCH_JSON" ]]; then
 fi
 
 # Read fields via python (jq not assumed available).
-read -r CLAUDE_SESSION_ID LEAD_MODEL_EXECUTION_VALUE PROJECT_ROOT_FROM_PY OKSTRA_RUNTIME_SETTINGS_FILE PROMPT_FILE < <(
+read -r CLAUDE_SESSION_ID LEAD_MODEL_EXECUTION_VALUE PROJECT_ROOT_FROM_PY PROMPT_FILE < <(
   okstra_py - "$LAUNCH_JSON" <<'PY'
 import json, sys
 d = json.loads(sys.argv[1])
-print(d["claudeSessionId"], d["leadModelExecutionValue"], d["projectRoot"], d["runtimeSettingsFile"], d["promptFile"])
+print(d["claudeSessionId"], d["leadModelExecutionValue"], d["projectRoot"], d["promptFile"])
 PY
 )
 
+# Note: per-session --settings injection was removed. okstra-ctl prepare
+# provisions <PROJECT_ROOT>/.claude/settings.local.json as a symlink to
+# ~/.okstra/templates/settings.local.json, which Claude Code auto-loads
+# whenever it runs inside that project — no CLI flag required.
 PROMPT="$(cat "$PROMPT_FILE")"
 cd "$PROJECT_ROOT_FROM_PY"
 CLAUDE_COMMAND=(claude --model "$LEAD_MODEL_EXECUTION_VALUE" --session-id "$CLAUDE_SESSION_ID")
-[[ -n "$OKSTRA_RUNTIME_SETTINGS_FILE" ]] && CLAUDE_COMMAND+=(--settings "$OKSTRA_RUNTIME_SETTINGS_FILE")
 CLAUDE_COMMAND+=("$PROMPT")
 exec "${CLAUDE_COMMAND[@]}"

package/runtime/python/okstra_ctl/run.py

@@ -23,7 +23,6 @@ import subprocess
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
 
 from okstra_project import upsert_project_json
 from .material import (
@@ -47,8 +46,9 @@ from .render import (
 )
 from .run_context import compute_and_write_run_context, write_run_inputs
 from .seeding import (
+    SettingsLinkError,
     cleanup_obsolete_generated_docs,
-    render_runtime_settings_file,
+    ensure_project_settings_symlink,
     verify_installation,
 )
 from .session import (
@@ -102,7 +102,6 @@ class PrepareInputs:
 class PrepareOutputs:
     ctx: dict
     prompt_text: str
-    runtime_settings_path: Optional[Path]
     extras: dict = field(default_factory=dict)
 
 
@@ -764,16 +763,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             file=__import__("sys").stderr,
         )
 
-    runtime_settings_path = None
     if not inp.render_only:
-        runtime_settings_path = render_runtime_settings_file(
-            workspace_root=workspace_root, run_dir=Path(ctx["RUN_DIR"]),
-        )
+        try:
+            link = ensure_project_settings_symlink(project_root=Path(inp.project_root))
+        except SettingsLinkError as exc:
+            print(
+                f"okstra-settings: failed to provision project settings symlink — "
+                f"worker dispatch may be blocked by Claude Code permissions. ({exc})",
+                file=__import__("sys").stderr,
+            )
+        else:
+            if link is None:
+                print(
+                    "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
+                    "re-run 'npx okstra@latest install' (0.14.0+) to provision the symlink target.",
+                    file=__import__("sys").stderr,
+                )
 
     return PrepareOutputs(
         ctx=ctx,
         prompt_text=prompt_text,
-        runtime_settings_path=runtime_settings_path,
         extras={"profile_content": profile_content},
     )
 
@@ -919,7 +928,6 @@ def main(argv: list[str]) -> int:
             "claudeSessionId": ctx["CLAUDE_SESSION_ID"],
             "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
             "projectRoot": ctx["PROJECT_ROOT"],
-            "runtimeSettingsFile": str(out.runtime_settings_path) if out.runtime_settings_path else "",
             "promptFile": str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"),
         }
         print(f"__OKSTRA_LAUNCH__ {json.dumps(machine)}")

package/runtime/python/okstra_ctl/seeding.py

@@ -1,13 +1,16 @@
-"""okstra runtime asset verification + per-run runtime settings.
+"""okstra runtime asset verification + project settings provisioning.
 
 okstra 가 깔아둔 런타임(`~/.okstra/lib/python`, `~/.okstra/bin`,
 `~/.okstra/version`) 이 있는지 확인하고, 누락 시 InstallationError 로
-surface 한다. 또한 claude 런치 때 사용할 휘발성 settings 파일을 현재 run
-디렉토리에 만든다.
+surface 한다. 또한 대상 프로젝트의 `.claude/settings.local.json` 을
+`~/.okstra/templates/settings.local.json` 으로 가리키는 symlink 로
+provision 해서, host Claude Code 세션이 같은 프로젝트에서 일하는 동안
+okstra worker wrapper 호출이 자동 허용되도록 한다.
 """
 from __future__ import annotations
 
-import shutil
+import os
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -16,6 +19,10 @@ class InstallationError(Exception):
     """okstra 가 깔아둔 런타임 자산이 누락됨."""
 
 
+class SettingsLinkError(Exception):
+    """`<project>/.claude/settings.local.json` symlink provisioning 실패."""
+
+
 def required_install_paths() -> list[Path]:
     """okstra install 이 채워야 하는 최소 자산 경로."""
     okstra_home = Path.home() / ".okstra"
@@ -82,16 +89,90 @@ def cleanup_obsolete_generated_docs(
             pass
 
 
-def render_runtime_settings_file(
-    *, workspace_root: Path, run_dir: Path,
-) -> Optional[Path]:
-    """`templates/reports/settings.template.json` 을 `<run-dir>/okstra-runtime-settings.json`
-    으로 복사한다. 템플릿 부재 시 None 반환(상위에서 `--settings` 인자 skip).
+def _okstra_home() -> Path:
+    """`~/.okstra` 의 절대경로. 테스트에서 `OKSTRA_HOME` 으로 override 가능."""
+    override = os.environ.get("OKSTRA_HOME", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / ".okstra"
+
+
+def installed_settings_template_path() -> Path:
+    """okstra install 이 만들어 둔 settings.local.json template 의 절대경로."""
+    return _okstra_home() / "templates" / "settings.local.json"
+
+
+def ensure_project_settings_symlink(*, project_root: Path) -> Optional[Path]:
+    """`<project_root>/.claude/settings.local.json` 을
+    `~/.okstra/templates/settings.local.json` 으로 가리키는 symlink 로
+    provisioning 한다.
+
+    Claude Code 가 그 프로젝트에서 host 세션으로 실행될 때 이 파일을
+    자동으로 로드하므로, okstra worker wrapper 호출(`okstra-codex-exec.sh`,
+    `okstra-gemini-exec.sh`) 이 별도 `--settings` 인자 없이도 허용된다.
+
+    반환값:
+      - target Path: symlink 가 새로 생성되었거나 이미 올바른 위치를
+        가리키고 있을 때.
+      - None: install 이 아직 settings template 을 깔지 않았을 때
+        (구버전 okstra install 등). 상위에서 경고로 흘려보낸다.
+
+    상위 호출자는 `SettingsLinkError` 만 처리하면 된다 — symlink target
+    의 dangling 여부, regular 파일 충돌, 사용자가 직접 만든 다른
+    symlink 등 의도된 boundary error 만 발생한다.
     """
-    template = Path(workspace_root) / "templates" / "reports" / "settings.template.json"
-    if not template.is_file():
+    project_root = Path(project_root)
+    template = installed_settings_template_path()
+    if not template.exists():
+        # install 이 0.13.x 이전 버전이면 templates/ 가 깔리지 않았을 수 있다.
+        # 상위에서 안내 메시지로 처리.
         return None
-    target = Path(run_dir) / "okstra-runtime-settings.json"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copyfile(template, target)
+
+    claude_dir = project_root / ".claude"
+    target = claude_dir / "settings.local.json"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+
+    # idempotent: 이미 올바른 target 을 가리키는 symlink 면 no-op.
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError as exc:
+            raise SettingsLinkError(
+                f"failed to read existing symlink {target}: {exc}"
+            ) from exc
+        if Path(current) == template or (claude_dir / current).resolve() == template.resolve():
+            return target
+        # okstra 가 관리하지 않는 다른 symlink 였으면 backup 후 교체.
+        _backup_and_replace(target, template)
+        return target
+
+    if target.exists():
+        # 일반 파일이 있으면 사용자 작성물일 가능성이 높다 — 손실 방지 backup.
+        _backup_and_replace(target, template)
+        return target
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
     return target
+
+
+def _backup_and_replace(target: Path, template: Path) -> None:
+    """기존 파일/심볼릭링크를 timestamped backup 으로 옮기고 새 symlink 생성."""
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    backup = target.with_name(f"{target.name}.bak.{stamp}")
+    try:
+        target.rename(backup)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to back up existing {target} to {backup}: {exc}"
+        ) from exc
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to create symlink {target} -> {template} after backup: {exc}"
+        ) from exc

package/runtime/skills/okstra-setup/SKILL.md

@@ -142,6 +142,37 @@ field → built-in default. Only edit when defaults don't cover the
 project's working files (e.g. additional cache or local-config dirs
 that must follow the executor into the worktree).
 
+## Step 4.6 (automatic): project-local Claude settings symlink
+
+`okstra setup` (and `okstra run` on its first invocation per project)
+provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
+`~/.okstra/templates/settings.local.json`. The template is installed
+by `okstra install` 0.14.0+ and contains the Bash permission rules
+required for the codex/gemini worker wrappers:
+
+- `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`
+- `Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)`
+
+Claude Code automatically loads `.claude/settings.local.json` whenever
+it operates inside that project, so okstra workers dispatched from
+**any** Claude Code session (host or okstra.sh-spawned) are allowed to
+run their wrapper scripts without further configuration.
+
+This replaces the previous per-run `--settings` injection model
+(`<run-dir>/okstra-runtime-settings.json`) and the earlier guidance to
+modify the user's global `~/.claude/settings.json`.
+
+If a non-symlink `.claude/settings.local.json` already exists, the
+setup step backs it up to `.claude/settings.local.json.bak.<timestamp>`
+before installing the symlink — surface that to the user so they can
+merge any project-specific rules back into a downstream file (the
+symlinked template is okstra-owned and gets refreshed when okstra
+updates).
+
+To opt out (advanced): replace the symlink with a regular file. okstra
+will detect that it is no longer a symlink on its next setup call and
+back it up as `.bak.<timestamp>` rather than overwriting silently.
+
 ## Step 5: Verify
 
 ```bash

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -270,6 +270,12 @@ Workers MUST omit `source` / `recordedAt` / `agent` / `agentRole` / `model` /
 Workers MUST use only `errorType: "tool-failure"` in the **sidecar file**.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four positional arguments: `<project-root> <model> <prompt-path> [<worktree-path>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt.
+- **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` on a 60-second cadence, capped at 30 minutes (1800s). The legacy "single foreground `Bash` with 120000ms timeout" rule is retired — it forced workers into ad-hoc background dispatch that lost stdout and silently broke Phase 5 synthesis. The new rule applies in **every phase** (analysis runs typically complete in 1–2 polls, so there is no regression for short jobs). Recording responsibilities:
+  - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
+  - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.
+  - 30-minute polling cap exceeded: call `KillShell(shell_id)` first, then record `cli-failure` with `--exit-code 124 --duration-ms 1800000 --message "<wrapper> exceeded 30m polling cap"`, then return the language-specific `*_CLI_TIMEOUT` sentinel.
+  - Token-usage matching is unaffected: the wrapper subagent stays alive throughout polling, so the wrapper's jsonl timestamp window continues to cover the underlying CLI rollout's full duration (see §"Token-usage accounting" below).
 - `contract-violation` events (C) are recorded by Lead via `okstra-error-log.py append-observed --error-type contract-violation ...` after inspecting worker outputs.
 - Lead's responsibility regarding the sidecar is to dump it to the run-level error log via `okstra-error-log.py append-from-worker` after each worker terminates; Lead does not write into the sidecar.
 

package/src/install.mjs

@@ -10,6 +10,11 @@ const AGENTS_MANIFEST_REL = "installed-agents.json";
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 
+// Source template (relative to runtime root in copy mode, or repo root in link mode).
+const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.json"];
+// Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
+const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -33,6 +38,7 @@ Usage:
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
+  ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
   ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
@@ -42,11 +48,17 @@ Effect (copy mode):
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
+  ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
   ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
+The settings.local.json file is the symlink target referenced by every
+project-local <project>/.claude/settings.local.json that okstra-setup
+provisions, granting per-project Claude Code permissions for okstra
+worker wrapper scripts without modifying the user's global settings.
+
 Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
 that Claude Code's subagent discovery picks them up; they cannot live
 inside the package alone because the harness only scans ~/.claude/agents/
@@ -228,6 +240,8 @@ async function installLinkMode(repoPath, paths, opts) {
   const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
 
+  await installSettingsTemplate(repoAbs, paths, { mode: "link", dryRun, quiet });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -376,6 +390,51 @@ async function installAgentsLink(repoAbs, opts) {
   return { installed: names };
 }
 
+async function installSettingsTemplate(srcRoot, paths, opts) {
+  const { mode, refresh = false, dryRun = false, quiet = false } = opts;
+  const src = join(srcRoot, ...SETTINGS_TEMPLATE_SRC_REL);
+  const dst = join(paths.home, ...SETTINGS_TEMPLATE_DST_REL);
+
+  if (!(await fileExists(src))) {
+    if (!quiet) process.stdout.write(`  settings template: source missing — skipped (${src})\n`);
+    return { installed: false };
+  }
+
+  if (!dryRun) await fs.mkdir(join(dst, ".."), { recursive: true });
+
+  if (mode === "link") {
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  settings template: ${action} (${dst} -> ${src})\n`);
+    return { installed: action !== "skipped" };
+  }
+
+  // copy mode — hash-skip mirrors copyTreeIfChanged behavior for a single file.
+  let needsCopy = refresh;
+  if (!needsCopy) {
+    try {
+      await fs.access(dst);
+      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
+      needsCopy = srcHash !== dstHash;
+    } catch {
+      needsCopy = true;
+    }
+  }
+
+  if (!needsCopy) {
+    if (!quiet) process.stdout.write(`  settings template: skipped (hash match)\n`);
+    return { installed: false };
+  }
+
+  if (dryRun) {
+    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
+  } else {
+    const buf = await fs.readFile(src);
+    await writeFileAtomic(dst, buf, 0o644);
+  }
+  if (!quiet) process.stdout.write(`  settings template: copied -> ${dst}\n`);
+  return { installed: true };
+}
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -507,6 +566,8 @@ export async function runInstall(args) {
   const agentResult = await installAgentsCopy(runtimeRoot, opts);
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
 
+  await installSettingsTemplate(runtimeRoot, paths, { mode: "copy", ...opts });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }

package/src/setup.mjs

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
-import { resolve as resolvePath } from "node:path";
+import { join, resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
@@ -283,6 +283,68 @@ export async function run(args) {
     return 1;
   }
 
-  process.stdout.write(JSON.stringify({ ok: true, ...result, projectJsonPath }, null, 2) + "\n");
+  let settingsSymlink = null;
+  try {
+    settingsSymlink = await ensureProjectSettingsSymlink(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to provision .claude/settings.local.json symlink — ` +
+        `host Claude Code sessions in this project may need to add wrapper permissions manually. (${err.message})\n`,
+    );
+  }
+
+  process.stdout.write(
+    JSON.stringify(
+      { ok: true, ...result, projectJsonPath, settingsLocalJson: settingsSymlink },
+      null,
+      2,
+    ) + "\n",
+  );
   return 0;
 }
+
+async function ensureProjectSettingsSymlink(projectRoot) {
+  const template = join(homedir(), ".okstra", "templates", "settings.local.json");
+  try {
+    await fs.access(template);
+  } catch {
+    return null; // install hasn't provisioned the template yet (pre-0.14 install)
+  }
+
+  const claudeDir = join(projectRoot, ".claude");
+  const target = join(claudeDir, "settings.local.json");
+  await fs.mkdir(claudeDir, { recursive: true });
+
+  let existingStat;
+  try {
+    existingStat = await fs.lstat(target);
+  } catch {
+    existingStat = null;
+  }
+
+  if (existingStat?.isSymbolicLink()) {
+    const current = await fs.readlink(target);
+    const resolved = current.startsWith("/") ? current : join(claudeDir, current);
+    if (resolved === template) return target;
+    await backupAndReplace(target, template);
+    return target;
+  }
+  if (existingStat) {
+    await backupAndReplace(target, template);
+    return target;
+  }
+
+  await fs.symlink(template, target);
+  return target;
+}
+
+async function backupAndReplace(target, template) {
+  const stamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*/, "")
+    .replace("T", "-");
+  const backup = `${target}.bak.${stamp}`;
+  await fs.rename(target, backup);
+  await fs.symlink(template, target);
+}

package/src/uninstall.mjs

@@ -180,6 +180,21 @@ export async function runUninstall(args) {
   }
   await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
 
+  await removePath(join(paths.home, "templates", "settings.local.json"), opts);
+  // Remove templates/ if now empty.
+  const templatesDir = join(paths.home, "templates");
+  if (await pathExists(templatesDir)) {
+    try {
+      const entries = await fs.readdir(templatesDir);
+      if (entries.length === 0) {
+        if (!opts.dryRun) await fs.rmdir(templatesDir);
+        if (!opts.quiet) process.stdout.write(`  removed empty: ${templatesDir}\n`);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);