okstra 0.13.1 → 0.14.0

package/README.kr.md

@@ -165,7 +165,7 @@ Claude Code 세션 밖에서 task 를 시작하려면:
 
 0.8.0 이후 `main` 에 추가된 workflow 변경:
 
-- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 prepare 시점의 `HEAD`. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **`--task-type implementation` 격리 worktree 자동 provisioning** — prepare 단계에서 `okstra-ctl` 이 `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>-<run-seq>` 를 수행해 격리된 working tree 와 브랜치 `<work-category-prefix>-<task-id-segment>-<run-seq>` (예: `feat-dev-9436-001`, `fix-dev-7311-002`) 를 만듭니다. base ref 는 사용자가 `--base-ref` 로 지정 (release-handoff PR base picker 와 동일한 메뉴: `main` / `dev` / `staging` / `preprod` / `prod` / 직접 입력). 첫 phase 에서는 필수이며, okstra-run skill 이 `AskUserQuestion` 으로 수집합니다 — 비대화형 호출자는 `--base-ref` 플래그를 직접 전달해야 prepare 가 통과합니다. Executor 와 verifier 모두 이 worktree 안에서 동작하므로 caller 의 작업 디렉터리는 깨끗하게 유지되고, worktree 는 PR 작성 · rollback 검증의 권위 artefact 로 남습니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 됩니다. 수동 cleanup: `git worktree remove <path>` → `git branch -D <branch>`. 상세: [`docs/kr/architecture.md`](docs/kr/architecture.md) *Task type* 섹션, [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — `final-verification` 이 `verdict=accepted` 를 반환한 직후에 실행되는 신규 phase. lead 가 Claude worker (drafter) 를 통해 commit message · PR body 후보를 만들고, `AskUserQuestion` 으로 사용자에게 (1) action (`commit only` / `commit + PR` / `skip`), (2) PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / 직접 입력), (3) message handling (`use as-is` / `edit then proceed` / `cancel`) 세 가지를 순서대로 묻습니다. 사용자가 메뉴로 선택한 git / gh 명령만 실행되고, force-push, base 브랜치 직접 push, hook bypass (`--no-verify`), release publish (`gh release`, `npm publish`, ...) 는 금지됩니다. 이 phase 에서는 소스 코드를 수정하지 않습니다. profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 
 ### 3.5 운영 명령

package/README.md

@@ -164,7 +164,7 @@ Notable flags added in 0.7.0 / 0.8.0:
 
 Recent workflow additions (post-0.8.0, on `main`):
 
-- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the main worktree's `HEAD` the first time a task-key is seen. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus removing the task-key entry from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
+- **Isolated task worktree for every task-type** — prepare automatically runs `git worktree add ~/.okstra/worktrees/<project>/<group>/<task>/` on a fresh branch `<work-category-prefix>-<task-id-segment>` branched from the **user-chosen base ref** (`--base-ref`, mirroring the `release-handoff` PR-base picker: `main` / `dev` / `staging` / `preprod` / `prod` / any local ref) the first time a task-key is seen. `--base-ref` is required on first phase; the okstra-run skill collects it via `AskUserQuestion`, non-interactive callers must pass the flag explicitly. Every subsequent phase of the same task-key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) reuses the same path and branch, so phase N inherits the working-tree state phase N-1 left behind. A global registry at `~/.okstra/worktrees/registry.json` (flock-guarded) reserves task-keys and branches across concurrent runs; all path/branch segments are sanitised (`/`, `:`, etc. → `-`). The worktree is preserved after every run for follow-up phases, PR authoring, and rollback. Skip paths: when the caller is already inside another worktree or `project_root` is not a git repo, provisioning no-ops. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus removing the task-key entry from the registry. Details: [`docs/kr/architecture.md`](docs/kr/architecture.md) (*Task type* section) and [`docs/kr/cli.md#--executor`](docs/kr/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs after `final-verification` returns `verdict=accepted`. The lead drafts a commit message and PR body via a Claude worker, then prompts the user with `AskUserQuestion` for three choices: action (`commit only` / `commit + PR` / `skip`), PR base branch (`staging` / `preprod` / `prod` / `main` / `dev` / free-form), and message handling (`use as-is` / `edit then proceed` / `cancel`). Only user-selected mutating git/gh commands run. Force-push, base-branch direct push, hook bypass (`--no-verify`), and release publishing (`gh release`, `npm publish`, ...) are forbidden. Source code is not edited in this phase. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 
 ### 3.5 Ops commands

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 세션 안에서 인계**
@@ -286,11 +286,14 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
   "projectId": "sample-project-v2-api",
   "projectRoot": "/Volumes/Workspaces/workspace/projects/sample-project",
   "createdAt": "2026-05-10T00:00:00Z",
-  "updatedAt": "2026-05-10T00:00:00Z"
+  "updatedAt": "2026-05-10T00:00:00Z",
+  "worktreeSyncDirs": [".project-docs", ".scratch", "graphify-out", ".claude"]
 }
 ```
 
-처음 실행이면 위 4-필드를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신합니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+처음 실행이면 위 4-필드(`projectId`, `projectRoot`, `createdAt`, `updatedAt`)를 새로 작성합니다. 이미 존재하면 `--project-id` 인자값과 저장된 `projectId` 가 일치하는지 검증한 뒤 `projectRoot`/`updatedAt` 만 갱신하고, 사용자가 추가한 알 수 없는 필드(`worktreeSyncDirs`, 향후 `mcpServers` 등)는 upsert 과정에서 보존됩니다. 불일치 시 즉시 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+`worktreeSyncDirs` (선택) 는 task worktree 로 symlink 할 project-root-relative 디렉토리 목록을 per-project 로 override 합니다. 해석 우선순위는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수 → `project.json` → built-in default (`.project-docs`, `.scratch`, `graphify-out`, `.claude`). 빈 배열을 지정하면 sync 자체를 비활성화합니다.
 
 `okstra-ctl` 의 reindex/backfill 도 신규 모델에서 권위 소스를 변경했습니다. 과거에는 `examples/projects/*.conf.sh` 를 source 했지만, 지금은 `~/.okstra/projects/<projectId>/meta.json` (record_start 가 위 project.json 정보를 mirror 한 결과) 을 스캔하여 (projectId, projectRoot) 매핑을 복원합니다. `OKSTRA_PROJECT_DEFINITION_DIR_OVERRIDE` 환경변수도 함께 폐기되었습니다.
 
@@ -321,7 +324,7 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 공통 제약:
 
 - `implementation`을 제외한 모든 phase는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다(`final-verification`은 read-only 테스트 명령만 허용). `implementation`은 승인된 plan의 파일 목록 안에서만 edit/commit이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API는 여전히 금지됩니다.
-- **모든 task-type 격리 worktree (BLOCKING)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 자동으로 task-key 단위 `git worktree` 를 생성하고, 같은 task-key 의 이후 phase (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 는 동일한 worktree·브랜치를 재사용합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화) 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 입니다. base ref 는 첫 phase prepare 시점의 main worktree `HEAD`. `~/.okstra/worktrees/registry.json` (flock-guarded) 가 task-key → path/branch 매핑을 전역 관리해 동시 실행 시 path·branch 충돌을 방지합니다. `.project-docs/`, `.scratch/`, `graphify-out/` 은 main worktree 에서 symlink 로 연결되어 모든 task 가 동일한 shared state 를 봅니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 후속 phase·PR 작성·rollback 검증의 권위 artefact 입니다. 수동 cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + registry 항목 삭제. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Task worktree* 블록과 `agents/SKILL.md` 의 *Task worktree (BLOCKING for every task-type)* 섹션 참고.
+- **모든 task-type 격리 worktree (BLOCKING)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 자동으로 task-key 단위 `git worktree` 를 생성하고, 같은 task-key 의 이후 phase (`requirements-discovery` → `error-analysis` → `implementation-planning` → `implementation`) 는 동일한 worktree·브랜치를 재사용합니다. 위치는 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` (segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화) 이고, 브랜치 이름은 `<work-category-prefix>-<task-id-segment>` (예: `feat-dev-9436`, `fix-dev-7311`) 입니다. base ref 는 첫 phase prepare 시점의 main worktree `HEAD`. `~/.okstra/worktrees/registry.json` (flock-guarded) 가 task-key → path/branch 매핑을 전역 관리해 동시 실행 시 path·branch 충돌을 방지합니다. `.project-docs/`, `.scratch/`, `graphify-out/`, `.claude/` 는 main worktree 에서 symlink 로 연결되어 모든 task 가 동일한 shared state 를 봅니다 (sync 대상 목록은 `project.json` 의 `worktreeSyncDirs` 또는 `OKSTRA_WORKTREE_SYNC_DIRS` 환경변수로 override 가능; 빈 배열이면 sync 비활성화). caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 executor 는 project_root 에서 그대로 작업합니다. worktree 는 run 종료 후 자동 삭제되지 않으며 후속 phase·PR 작성·rollback 검증의 권위 artefact 입니다. 수동 cleanup: `git -C <main-worktree> worktree remove <path>` → `git -C <main-worktree> branch -D <branch>` + registry 항목 삭제. 자세한 동작은 `prompts/profiles/implementation.md` 의 *Task worktree* 블록과 `agents/SKILL.md` 의 *Task worktree (BLOCKING for every task-type)* 섹션 참고.
 - `implementation` 과 `release-handoff` 를 제외한 모든 phase 는 source code edit, build, migration, deployment, 그 밖의 state-mutating 명령을 금지합니다 (`final-verification` 은 read-only 테스트 명령만 허용). `implementation` 은 승인된 plan 의 파일 목록 안에서만 edit/commit 이 허용되며, `git push`·publish·deploy·실제 migration·third-party write API 는 여전히 금지됩니다. `release-handoff` 는 source code 자체는 수정하지 않고, 사용자가 메뉴로 선택한 commit / push / PR 명령만 실행합니다 (force push, base 브랜치 직접 push, hook bypass, release publish 는 여전히 금지).
 - 사용자가 "다음 단계 진행해" 같은 표현을 보내도, 그 발화만으로 다음 phase가 자동 시작되지 않습니다. 다음 phase는 새 `okstra.sh` 실행으로만 시작합니다.
 - **Authority & permissions assumption (HARD RULE — 모든 task-type 및 `okstra-schedule` 공통)**: 사용자(및 팀)는 예상되는 모든 작업에 대해 완전한 권한·승인 권한을 보유한다고 가정합니다. 외부 승인, 서드파티 액세스, 역할/IAM 권한, 조직적 sign-off, 법무·보안 검토, 벤더 협의, "권한 보유 여부 확인" 같은 항목을 routing 결정·missing inputs·clarification questions·risk·dependency·open questions·effort/day 추정에 포함하지 않습니다. okstra 내부 phase 핸드오프(`User Approval Request` 등)는 사용자 본인이 즉시 승인 가능한 내부 게이트이므로 영향 없으며, `implementation`의 forbidden actions(`git push`, prod deploy, shared-DB migration 등)도 권한 사유가 아닌 **안전 사유**로 계속 적용됩니다.

package/docs/kr/cli.md

@@ -227,7 +227,7 @@ scripts/okstra.sh --task-type implementation-planning ... \
 ### `--workers`
 
 이번 run에서 사용할 worker 목록을 직접 지정합니다.
-생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+생략하면 기본값 `claude,codex,report-writer`를 사용합니다. Gemini worker는 옵션이며 필요할 때 `--workers claude,codex,gemini,report-writer` 와 같이 명시적으로 추가하세요.
 지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
 
 예:
@@ -287,7 +287,7 @@ fallback 기본값은 아래와 같습니다.
 - Executor 는 이 run 에서 **유일하게 프로젝트 파일을 mutate 할 수 있는 worker** 입니다. 나머지 두 provider 는 같은 run 에서 strict read-only verifier 로 dispatch 됩니다.
 - Executor 의 모델은 provider 별 worker 모델 플래그를 그대로 재사용합니다. 즉 `--executor codex` 이면 Executor 의 모델은 `--codex-model` (기본 `gpt-5.5`), `--executor gemini` 이면 `--gemini-model` (기본 `auto`) 가 됩니다.
 - Claude/Codex/Gemini 세 verifier 는 executor provider 와 관계없이 항상 dispatch 됩니다. Executor 와 같은 provider 라도 별도 CLI 세션으로 verifier 가 호출되어 context 가 분리되므로 self-review 안전장치는 유지됩니다.
-- 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --full-auto`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
+- 실제 파일 변경은 Codex/Gemini 의 경우 각 CLI 의 auto-edit 모드 (예: `codex exec --sandbox workspace-write`) 를 통해 일어나며, Claude-side Edit/Write tool 을 거치지 않습니다.
 - **Task worktree (모든 task-type 자동 격리)**: 모든 task-type 의 첫 번째 phase prepare 단계에서 `okstra-ctl` 이 `~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>/` 에 `git worktree` 를 생성하고, 브랜치 `<work-category-prefix>-<task-id-segment>` 를 main worktree `HEAD` 에서 분기합니다. 같은 task-key 의 이후 phase 는 동일한 path/branch 를 재사용하므로 status 가 `reused` 로 기록됩니다 (run-prep 시점에 새 `git worktree add` 가 일어나지 않음). 모든 segment 의 `/`·`:` 등 특수문자는 `-` 로 정규화되며, `~/.okstra/worktrees/registry.json` 가 task-key → path/branch 매핑을 전역 관리합니다 (flock-guarded). Executor 의 Edit/Write/build/test/commit, verifier 의 read 는 모두 이 worktree 안에서 수행됩니다. caller 가 이미 다른 worktree 안에 있거나 project_root 가 git repo 가 아니면 provisioning 은 skip 되고 status 가 `skipped-in-worktree` / `skipped-not-git` 로 기록됩니다. 경로·브랜치 충돌은 `PrepareError` 로 즉시 실패시키며, run 종료 후 worktree 는 자동 삭제하지 않습니다 (수동: `git worktree remove` → `git branch -D` + registry 항목 삭제).
 
 예:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "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.1",
-  "builtAt": "2026-05-13T01:13:31.365Z",
+  "package": "0.14.0",
+  "builtAt": "2026-05-13T02:55:11.516Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -105,7 +105,7 @@ For `--task-type implementation` runs, the task bundle additionally pins one of
 
 Lead MUST dispatch Edit/Write-bearing work only through the `workerAgent` declared there. The other two providers still run as read-only verifiers in the same run; the executor's own provider is *also* dispatched separately as a verifier (a fresh CLI session) so the diff is reviewed by a context-isolated session. Session isolation is the primary self-review safeguard — same-model executor and same-provider verifier is acceptable when running in distinct sessions. Selecting a different model variant (e.g. executor=opus / Claude verifier=sonnet) is recommended but no longer mandatory.
 
-Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--gemini-model`). For Codex/Gemini executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`), not through Claude-side Edit/Write tools.
+Executor is chosen at run-prep time via `--executor <claude|codex|gemini>` (or `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`); the model used by the executor is taken from the corresponding worker model flag (`--claude-model` / `--codex-model` / `--gemini-model`). For Codex/Gemini executors, the underlying file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`), not through Claude-side Edit/Write tools.
 
 #### Task worktree (BLOCKING for every task-type)
 

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

@@ -32,7 +32,7 @@ $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-mode
 
 The wrapper internally runs:
 ```bash
-codex exec -C "<project-root>" --model "<model>" --full-auto - < "<prompt-path>" 2>/dev/null
+codex exec -C "<project-root>" --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:*)`.
@@ -71,7 +71,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```bash
    $HOME/.okstra/bin/okstra-codex-exec.sh "<absolute-project-root>" "<assigned-model-execution-value>" "<absolute-prompt-history-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`, `--full-auto`, 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.
+   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.
 
 8. Return the codex output as-is without modification.
 

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

@@ -50,4 +50,4 @@ 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" --full-auto - < "$prompt_path" 2>/dev/null
+exec codex exec -C "$project_root" --model "$model" --sandbox workspace-write - < "$prompt_path" 2>/dev/null

package/runtime/bin/okstra.sh

@@ -119,6 +119,7 @@ PY_ARGS=(
 [[ "$APPROVE_PLAN_ACK" == "true" ]] && PY_ARGS+=(--approve)
 [[ -n "${CLARIFICATION_RESPONSE_PATH-}" ]] && PY_ARGS+=(--clarification-response "$CLARIFICATION_RESPONSE_PATH")
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
+[[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$REFRESH_OKSTRA_ASSETS" == "true" ]] && PY_ARGS+=(--refresh-assets)
 
@@ -151,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/prompts/profiles/implementation.md

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the verifier set; when omitted only the Claude+Codex verifiers participate (`--executor gemini` is therefore not selectable without explicitly listing `gemini` in `--workers`)
 - **Executor binding (resolved at run-prep time, fixed for this run):**
   - Executor display name: `{{EXECUTOR_DISPLAY_NAME}}`
   - Executor provider: `{{EXECUTOR_PROVIDER}}` (one of: `claude` | `codex` | `gemini`; chosen via `--executor` or `OKSTRA_DEFAULT_EXECUTOR`, default `claude`)
@@ -13,12 +14,12 @@
   - Executor model: `{{EXECUTOR_MODEL_DISPLAY}}` (launch value: `{{EXECUTOR_MODEL_EXECUTION_VALUE}}`)
   - Wherever this profile mentions the `Executor`, it refers to the role bound above. The other two providers in the roster (`claude` / `codex` / `gemini` minus the executor) are dispatched as **verifiers only** for this run and remain strictly read-only.
 {{INCLUDE:_common-contract.md}}
-- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier triad in this phase):
-  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --full-auto`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
-  - **Verifier roles:** the three verifier slots are `Claude verifier`, `Codex verifier`, and `Gemini verifier`. All three are dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
+- Team contract (phase-specific overrides — `Claude worker` is replaced by `Executor` + verifier set in this phase):
+  - **Executor role:** the `Executor` (bound above) is the **only worker permitted to use Edit / Write / state-mutating Bash commands** on project files. All other workers run read-only. When the executor provider is `codex` or `gemini`, the actual file mutation happens inside the executor CLI's own auto-edit mode (e.g. `codex exec --sandbox workspace-write`, gemini's equivalent) — not through Claude-side Edit/Write tools — but the safety rules in this profile still apply identically.
+  - **Verifier roles:** the verifier slots are `Claude verifier` and `Codex verifier`, plus `Gemini verifier` **only when `gemini` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
   - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
-  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto`. The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
-  - **All-verifier-failure policy**: if every verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or two verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
+  - Phase-specific model defaults override the shared defaults: `Claude verifier`=`sonnet`, `Codex verifier`=`gpt-5.5`, `Gemini verifier`=`auto` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `sonnet`, override to `opus` recommended when this run's executor is claude), codex→`--codex-model` (default `gpt-5.5`), gemini→`--gemini-model` (default `auto`).
+  - **All-verifier-failure policy**: if every verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) ends with a non-result terminal status (`timeout`, `error`, `not-run`) — i.e. zero independent verdicts were produced — the run MUST end with status `blocked` and route to a follow-up `error-analysis` run. `Claude lead` MUST NOT substitute its own verdict in place of the missing verifier outputs; synthesis requires at least one independent verifier's verdict. If one or more verifiers fail but at least one returns a verdict, the run proceeds with the surviving verdict(s) and the final report MUST explicitly notate which verifiers were unavailable, with the captured error / timeout evidence per failed verifier.
 - Pre-implementation gate (mandatory — refuse to start if any item fails):
   - the run brief MUST cite `--approved-plan <path>` pointing to a `final-report.md` produced by a prior `implementation-planning` run located under `runs/implementation-planning/.../reports/final-report.md`
   - that file MUST contain a `User Approval Request` block (canonically placed at the **top of the report**, immediately under the metadata header) AND a recorded user approval marker. The canonical, recommended form is the single markdown checkbox line `- [x] Approved`. The runtime regex in `okstra_ctl.run._validate_approved_plan` also accepts (case-insensitive, line-anchored, optional leading `-`/`*`/`+` bullet): `APPROVED` (alone, followed by `:`, or end-of-line), `[x] Approved`, or `User Approval: APPROVED|granted|yes`. Free-form approvals such as "lgtm", "go ahead", or paraphrased confirmations are intentionally NOT accepted; if the user's approval is informal, re-edit the plan file to flip the top checkbox to `- [x] Approved` before invoking the implementation run.
@@ -34,7 +35,7 @@
   - Base ref: `{{EXECUTOR_WORKTREE_BASE_REF}}` — commit SHA the worktree was branched from at the first phase; canonical `<base>` for every `git diff` / `git log` in this run.
   - Provisioning note: `{{EXECUTOR_WORKTREE_NOTE}}`
   - **Executor behaviour**: when status is `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the working tree path above as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files; if a file outside the worktree is needed, the dependency is a planning gap — record it in `Out-of-plan edits` and continue.
-  - **Verifier behaviour**: all three verifier roles read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
+  - **Verifier behaviour**: all verifier roles in the resolved roster read from the SAME working tree path so they observe the exact diff the Executor produced. Verifiers remain strictly read-only there.
   - **Lifecycle**: the worktree is kept after the run completes (no automatic cleanup) and is reused by every subsequent phase of the same task-key. Cleanup, when the task is fully done, is manual: `git -C <main-worktree> worktree remove <path>` followed by `git -C <main-worktree> branch -D <branch>`, plus removing the task-key entry from `~/.okstra/worktrees/registry.json`.
   - **Skipped paths**: when status is `skipped-in-worktree` or `skipped-not-git`, the executor operates in `project_root` as before. Cite the status in the final report's metadata header so reviewers know which path was taken.
   - **Synced state directories (symlinks into the MAIN worktree)**: at provision time `okstra-ctl` symlinks `.project-docs/`, `.scratch/`, and `graphify-out/` from the repo's **main worktree** into the task worktree (override via `OKSTRA_WORKTREE_SYNC_DIRS`; empty string disables). These are NOT independent copies — writes through them land in the main worktree. Inside this run the executor MUST confine writes under these paths to its own task scope (i.e. only `.project-docs/okstra/tasks/<this-task-id>/...`). Reading from elsewhere under the symlinks (other tasks, `graphify-out/GRAPH_REPORT.md`, `.scratch/` issues) is allowed and expected for context.
@@ -84,7 +85,7 @@
   - **Out-of-plan edits block**: every file edited that was not in the approved plan's file list, with rationale (empty block is acceptable and preferred)
   - **Validation evidence**: actual command output (stdout/stderr) for every `pre / mid / post` validation command from the plan. Truncated output is acceptable but the command line and exit code MUST be exact. No paraphrasing of test results.
   - **TDD evidence (when applicable)**: for steps that should be TDD-ordered, show the failing-test output BEFORE the implementation commit and the passing-test output AFTER, with commit SHAs framing the transition.
-  - **Verifier results**: a section per verifier (`Gemini verifier`, `Codex verifier`, `Claude verifier`) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse three opinions into one paragraph.
+  - **Verifier results**: a section per verifier present in the resolved roster (`Claude verifier`, `Codex verifier`, and `Gemini verifier` when opted in) containing their independent verdict (PASS / CONCERNS / FAIL), their cited diff snippets, and any fix recommendations they declined to apply. `Claude lead` synthesises a unified verdict but MUST preserve dissent — do not collapse opinions into one paragraph.
   - **Rollback verification**: confirmation that the plan's rollback path is still valid after the changes. Strength of verification depends on the change category:
     - **Pure code changes** (no persisted state, no infra mutation): a reachable revert SHA is sufficient. Record the exact `git revert <SHA>` command that would undo the change, and confirm `git rev-parse <SHA>` resolves.
     - **Feature-flag-gated changes**: confirm the off-switch path was exercised in this run's validation evidence (i.e. one of the validation commands ran with the flag off and succeeded). A plan that ships a flag without exercising the off-path does NOT satisfy this requirement.
@@ -95,7 +96,7 @@
   1. **Plan coverage** — every step in the approved plan's recommended option must point to a commit (or an explicit `Skipped: <reason>` entry). List gaps.
   2. **Evidence completeness** — every `Validation evidence` and `TDD evidence` claim has the actual command line and exit code? No paraphrased "tests pass" without output?
   3. **Out-of-plan honesty** — files in the diff that are NOT in the plan list must appear in the `Out-of-plan edits` block. Cross-check with `git diff --name-only`.
-  4. **Verifier dissent preserved** — if the three verifiers disagree, the disagreement is visible in the report? Synthesis hides nothing?
+  4. **Verifier dissent preserved** — if the verifiers in the resolved roster disagree, the disagreement is visible in the report? Synthesis hides nothing?
   5. **Forbidden action audit** — `git push`, publish, deploy, migration, third-party write commands: scan the run's session transcripts for any occurrence and confirm none happened.
   6. **Placeholder scan** — restrict the scan to lines this run actually introduced; pre-existing placeholders in unchanged regions of touched files are out of scope. Required command (substitute `<base>` with the parent of the first commit in this run's commit list):
      ```

package/runtime/python/lib/okstra/cli.sh

@@ -144,6 +144,10 @@ while [[ $# -gt 0 ]]; do
       WORK_CATEGORY="$(require_option_value --work-category "${2-}")"
       shift 2
       ;;
+    --base-ref)
+      BASE_REF="$(require_option_value --base-ref "${2-}")"
+      shift 2
+      ;;
     --task-type)
       ANALYSIS_TYPE="$(require_option_value --task-type "${2-}")"
       shift 2

package/runtime/python/lib/okstra/globals.sh

@@ -26,6 +26,7 @@ GEMINI_MODEL_OVERRIDE=""
 REPORT_WRITER_MODEL_OVERRIDE=""
 EXECUTOR_OVERRIDE=""
 WORK_CATEGORY=""
+BASE_REF=""
 RELATED_TASKS_RAW=""
 ANALYSIS_TYPE=""
 BRIEF_PATH=""
@@ -150,7 +151,7 @@ GEMINI_WORKER_MODEL_DISPLAY=""
 GEMINI_WORKER_MODEL_EXECUTION_VALUE=""
 REPORT_WRITER_MODEL_DISPLAY=""
 REPORT_WRITER_MODEL_EXECUTION_VALUE=""
-DEFAULT_WORKERS="claude,codex,gemini,report-writer"
+DEFAULT_WORKERS="claude,codex,report-writer"
 DEFAULT_LEAD_MODEL_NAME="${OKSTRA_DEFAULT_LEAD_MODEL:-opus}"
 DEFAULT_CLAUDE_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CLAUDE_MODEL:-sonnet}"
 DEFAULT_CODEX_WORKER_MODEL_NAME="${OKSTRA_DEFAULT_CODEX_MODEL:-gpt-5.5}"

package/runtime/python/lib/okstra/usage.sh

@@ -65,7 +65,8 @@ options:
   --refresh-assets    Deprecated. okstra now installs skills/agents into ~/.claude and the codex
                       wrapper into ~/.okstra/bin via scripts/okstra-install.sh. Re-run that
                       installer with --refresh to update installed assets.
-  --workers            Comma-separated worker list for this run. Default: claude,codex,gemini,report-writer
+  --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
+                      (Gemini worker is optional; add `gemini` explicitly, e.g. --workers claude,codex,gemini,report-writer)
   --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or sonnet
   --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.5
@@ -83,6 +84,12 @@ options:
                        Defaults to 'unknown' when omitted. Use this when the
                        lifecycle skipped --task-type=requirements-discovery
                        (where work-category would otherwise be inferred).
+  --base-ref           Git ref (branch name, tag, or commit SHA) used as the
+                       base of the per-task worktree on the FIRST phase of a
+                       task-key. Required on first phase; ignored on
+                       subsequent phases (the registered worktree is reused).
+                       Typical values mirror the release-handoff PR-base picker:
+                       main | dev | staging | preprod | prod | any local ref.
   --task-type          Set the task purpose for this run and select the matching profile file.
   -h, --help           Show this help.
 

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 (
@@ -90,6 +90,7 @@ class PrepareInputs:
     executor: str = ""
     related_tasks_raw: str = ""
     work_category: str = ""
+    base_ref: str = ""
     approved_plan_path: str = ""
     clarification_response_path: str = ""  # absolute or empty
     render_only: bool = False
@@ -101,7 +102,6 @@ class PrepareInputs:
 class PrepareOutputs:
     ctx: dict
     prompt_text: str
-    runtime_settings_path: Optional[Path]
     extras: dict = field(default_factory=dict)
 
 
@@ -504,6 +504,15 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         raise PrepareError(
             f"--executor must be one of: claude, codex, gemini (got: {executor_provider!r})"
         )
+    if (
+        inp.task_type == "implementation"
+        and executor_provider not in workers
+    ):
+        raise PrepareError(
+            f"--executor {executor_provider} requires {executor_provider!r} in "
+            f"--workers, but resolved roster is {workers!r}. "
+            f"Add it explicitly, e.g. --workers {','.join(sorted(set(workers + [executor_provider])))}."
+        )
     executor_provider_to_meta = {
         "claude": ("Claude executor", "claude-worker", cw),
         "codex": ("Codex executor", "codex-worker", co),
@@ -537,6 +546,8 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             task_group_segment=ctx["TASK_GROUP_SEGMENT"],
             task_id_segment=ctx["TASK_ID_SEGMENT"],
             work_category=inp.work_category,
+            base_ref=inp.base_ref,
+            require_base_ref=True,
         )
     except RuntimeError as exc:
         raise PrepareError(f"task worktree provisioning failed: {exc}") from exc
@@ -752,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},
     )
 
@@ -818,6 +839,19 @@ def main(argv: list[str]) -> int:
             "Falls back to `unknown` when omitted."
         ),
     )
+    p.add_argument(
+        "--base-ref",
+        default="",
+        dest="base_ref",
+        help=(
+            "Git ref (branch name, tag, or commit SHA) used as the base of "
+            "the task worktree on the first phase of this task-key. "
+            "Required for first-phase prepare; ignored on subsequent phases "
+            "(the registered worktree is reused). Mirrors the PR-base picker "
+            "used by the `release-handoff` phase: typical values are "
+            "`main` / `dev` / `staging` / `preprod` / `prod` or any local ref."
+        ),
+    )
     args = p.parse_args(argv)
 
     project_root = Path(args.project_root).expanduser().resolve()
@@ -854,6 +888,7 @@ def main(argv: list[str]) -> int:
         executor=args.executor,
         related_tasks_raw=args.related_tasks_raw,
         work_category=args.work_category,
+        base_ref=args.base_ref,
         approved_plan_path=args.approved_plan_path,
         clarification_response_path=clarification_abs,
         render_only=args.render_only,
@@ -893,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/python/okstra_ctl/worktree.py

@@ -161,6 +161,17 @@ def _head_sha(cwd: Path) -> str:
     return res.stdout.strip()
 
 
+def _resolve_commit_sha(cwd: Path, ref: str) -> str:
+    """Resolve a user-supplied ref (branch, tag, short/long SHA) to a full
+    commit SHA in `cwd`. Returns empty string when the ref is not resolvable
+    so the caller can raise a contextual error.
+    """
+    res = _git(cwd, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}")
+    if res.returncode != 0:
+        return ""
+    return res.stdout.strip()
+
+
 def _main_worktree_path(project_root: Path) -> Path:
     """Locate the repository's MAIN worktree (the original checkout).
 
@@ -292,6 +303,8 @@ def provision_task_worktree(
     task_group_segment: str,
     task_id_segment: str,
     work_category: str,
+    base_ref: str = "",
+    require_base_ref: bool = False,
 ) -> WorktreeProvision:
     """Materialise (or reuse) the task worktree for this run.
 
@@ -299,6 +312,13 @@ def provision_task_worktree(
     Subsequent phases of the same task-key look up the registry and
     return the existing path + branch unchanged.
 
+    ``base_ref`` is the ref (branch name, tag, or commit SHA) to branch
+    the new worktree from on first phase. When empty, the main worktree's
+    current ``HEAD`` is used (legacy default; the CLI enforces a
+    non-empty value on first phase so callers go through the
+    AskUserQuestion menu in the okstra-run skill). Subsequent phases
+    ignore ``base_ref`` — the registered entry's base is reused.
+
     Raises:
         RuntimeError when worktree creation fails (path clash on disk
         that the registry does not know about, branch clash with a
@@ -369,16 +389,34 @@ def provision_task_worktree(
         )
 
     main_root = _main_worktree_path(project_root)
-    base_ref = _head_sha(main_root)
-    if not base_ref:
+    requested_base = (base_ref or "").strip()
+    if not requested_base and require_base_ref:
         raise RuntimeError(
-            "could not resolve HEAD sha in main worktree; cannot create task worktree"
+            "first-phase task worktree requires an explicit base ref; "
+            "pass `--base-ref <branch|tag|sha>` (or invoke through the "
+            "okstra-run skill which collects this interactively)"
         )
+    if requested_base:
+        resolved_sha = _resolve_commit_sha(main_root, requested_base)
+        if not resolved_sha:
+            raise RuntimeError(
+                f"could not resolve base ref `{requested_base}` in main worktree "
+                f"({main_root}); ensure the branch/tag/SHA exists locally"
+            )
+        resolved_base_ref = resolved_sha
+        base_origin = requested_base
+    else:
+        resolved_base_ref = _head_sha(main_root)
+        if not resolved_base_ref:
+            raise RuntimeError(
+                "could not resolve HEAD sha in main worktree; cannot create task worktree"
+            )
+        base_origin = "HEAD"
 
     worktree_path.parent.mkdir(parents=True, exist_ok=True)
     res = _git(
         main_root,
-        "worktree", "add", "-b", branch, str(worktree_path), base_ref,
+        "worktree", "add", "-b", branch, str(worktree_path), resolved_base_ref,
     )
     if res.returncode != 0:
         raise RuntimeError(
@@ -398,7 +436,7 @@ def provision_task_worktree(
             task_id=safe_task,
             worktree_path=str(worktree_path),
             branch=branch,
-            base_ref=base_ref,
+            base_ref=resolved_base_ref,
             phase=task_type,
         )
     except RuntimeError:
@@ -408,13 +446,18 @@ def provision_task_worktree(
         _git(main_root, "branch", "-D", branch)
         raise
 
+    base_label = (
+        f"{base_origin} @ {resolved_base_ref[:12]}"
+        if base_origin != "HEAD"
+        else f"HEAD @ {resolved_base_ref[:12]}"
+    )
     return WorktreeProvision(
         status="created",
         path=str(worktree_path),
         branch=branch,
-        base_ref=base_ref,
+        base_ref=resolved_base_ref,
         note=(
             f"task worktree created at {worktree_path} on branch {branch} "
-            f"(base {base_ref[:12]}; phase {task_type}){linked_suffix}"
+            f"(base {base_label}; phase {task_type}){linked_suffix}"
         ),
     )

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

@@ -141,6 +141,58 @@ If `implementation` chosen, ask two more `AskUserQuestion` in order:
 - `"Path to the approved final-report.md (must contain APPROVED marker)"` — the underlying python `prepare_task_bundle` re-validates the marker, but you can pre-check with `grep`.
 - `"Executor provider for this run (claude | codex | gemini)?"` — only this provider mutates project files; the other two run as read-only verifiers. Default `claude` (or `OKSTRA_DEFAULT_EXECUTOR` if set). Pass the answer through `PrepareInputs.executor`.
 
+## Step 4.6: Base ref for the task worktree (first phase only)
+
+`okstra prepare` provisions a per-task git worktree on first phase of a task-key
+and reuses it on every subsequent phase. The base ref of that worktree is the
+**user's choice**, not the caller's current `HEAD`, so the worktree never
+silently inherits an unrelated branch you happen to be checked out on.
+
+First, decide whether to ask:
+
+```bash
+python3 - <<PY
+import sys
+from pathlib import Path
+sys.path.insert(0, "$OKSTRA_PYTHONPATH".split(":")[0])
+from okstra_ctl import worktree_registry
+from okstra_ctl.ids import _safe_fs_segment
+entry = worktree_registry.lookup(
+    _safe_fs_segment("<project-id>"),
+    _safe_fs_segment("<task-group>"),
+    _safe_fs_segment("<task-id>"),
+)
+print("REUSE" if (entry and entry.status == "active") else "ASK")
+PY
+```
+
+- `REUSE` → the registered worktree is reused; set `base_ref=""` and skip the
+  question (the registered base is authoritative).
+- `ASK` → this is the first phase for this task-key. Continue.
+
+`AskUserQuestion` (mirrors the `release-handoff` PR-base picker):
+
+- **Label**: `"이 task worktree 의 base branch?"`
+- **Options** (single-select):
+  1. `main` (recommended)
+  2. `dev`
+  3. `staging`
+  4. `preprod`
+  5. `prod`
+  6. Free text — let the user type any local ref (branch, tag, or full/short SHA).
+
+Validate the chosen ref exists in the MAIN worktree before continuing:
+
+```bash
+git -C "$(git -C "$PROJECT_ROOT" rev-parse --path-format=absolute --git-common-dir | xargs dirname)" \
+    rev-parse --verify --quiet "<chosen-ref>^{commit}" >/dev/null \
+  || { echo "ref not found locally: <chosen-ref>"; exit 1; }
+```
+
+Re-ask on failure. Echo the resolved short SHA back to the user
+(`base 확정: <ref> (<short-sha>)`) and capture `base_ref=<chosen-ref>` for
+Step 7.
+
 ## Step 5: Brief path
 
 - New task: `AskUserQuestion` (free text) `"Path to the task brief markdown (relative to project root)"`. Verify file exists; re-ask on failure.
@@ -169,7 +221,7 @@ Do NOT ask for `workers_override` in implementation — the profile's required r
 
 Ask each in turn (free text, blank = default):
 
-1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값). 선택지: claude, codex, gemini, report-writer"` → `workers_override`
+1. `"참여 워커 목록 (쉼표 구분, 빈 칸 = 프로필 기본값 claude,codex,report-writer). 선택지: claude, codex, gemini, report-writer — gemini는 옵션이므로 필요할 때 명시"` → `workers_override`
 2. `"리더(Claude lead) 모델? (빈 칸 = 기본값)"` → `lead_model`
 3. `"claude 워커 모델? (빈 칸 = 기본값)"` → `claude_model`
 4. `"codex 워커 모델? (빈 칸 = 기본값)"` → `codex_model`
@@ -189,6 +241,7 @@ Before calling `prepare_task_bundle`, echo the resolved selections back to the u
 선택 확인:
   task-type     : implementation
   task-key      : <group>/<id>
+  base-ref      : main (resolved <short-sha>)   ← worktree base, first phase only
   executor      : codex
   workers       : (프로필 기본 — executor + verifier 2 + report-writer)
   lead-model    : default (opus)
@@ -231,6 +284,7 @@ out = prepare_task_bundle(PrepareInputs(
     gemini_model="...", report_writer_model="...",
     related_tasks_raw="...",
     executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
+    base_ref="<chosen-ref-from-step-4.6 or empty when reusing existing worktree>",
     approved_plan_path="<approved-plan-or-empty>",
     clarification_response_path=str(clarification_abs) if clarification_abs else "",
     render_only=True,

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/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);