thehood 0.1.0-preview.0

package/docs/ROLE_CONTRACTS.md

@@ -0,0 +1,252 @@
+# Role Contracts
+
+Role contracts define what each agent is responsible for, what it may access, and what it must return.
+
+The same model provider can fill different roles across different runs, but a single agent instance must not hold conflicting powers inside the same run.
+
+## Role Matrix
+
+| Role | Responsibility | Edit Tools | Shell Tools | Acceptance Power |
+| --- | --- | --- | --- | --- |
+| Orchestrator | Plan, delegate, compare evidence, control loop | No by default | Limited | No final authority without evidence |
+| Planner | Create implementation plan and risks | No | Read-only | No |
+| Researcher | Inspect repo, docs, logs, and external references | No | Read/search only | No |
+| Implementer | Make scoped code changes | Yes, scoped | Yes, scoped | No |
+| QA Tester | Find missed cases and recommend validation from evidence | No | Read-only | No |
+| Verifier | Validate output against acceptance criteria | No | Test/log tools only | Recommends approve/revise/abort |
+| Critic | Find risks, missing cases, design flaws | No | Read-only | No |
+| Integrator | Apply approved patches | Yes, deterministic | Limited | No |
+| Citation Agent | Verify evidence and attribution | No | Read/search only | No |
+
+## Hard Invariants
+
+- Implementer and verifier cannot be the same agent for the same task.
+- Verifier cannot edit files.
+- QA tester cannot edit files.
+- Critic cannot edit files.
+- Researcher cannot edit files.
+- Integrator applies only approved patches.
+- Runtime command logs beat model summaries.
+- Test changes must be explicit and separately reviewed.
+
+## Same-Run Summons
+
+A summon is a runtime-owned read-only call to an existing role on an existing run. It is how the runtime can ask a planner, researcher, QA tester, verifier, or critic to review a slice, perform QA, challenge assumptions, or gather evidence without changing the main loop owner.
+
+Summons carry:
+
+- role
+- kind such as `review`, `qa`, `critique`, `research`, or `plan`
+- brief and optional persona
+- constraints
+- artifact refs used as evidence
+- optional one-call provider assignment
+
+A summon does not grant edit tools, apply patches, accept work, or rewrite the run's role mapping. Model-backed summon providers still require provider-invocation approval unless autopilot policy auto-approves the bounded gate.
+
+Summon responses can appear as read-only sidecar evidence on review ownership lanes. They are useful for QA, critique, and second opinions, but they cannot satisfy required verifier ownership, replace runtime-captured validation evidence, or advance the main state machine.
+
+A fan-out is a bounded group of summons on the same run. It uses the same read-only role limits, provider approval gates, and sidecar evidence rules as individual summons. Active approval gates stop later fan-out items, while contained advisory provider failures are recorded without granting those failures acceptance authority. Fan-out writes a compact group artifact for visibility, but it does not create a new scheduler, grant edit tools, or satisfy required review gates.
+
+Crew lane trails are runtime-derived display views over role responsibilities, review ownership, and handoffs. They make the hood readable as planner, builder, QA, verifier, critic, integrator, operator, reconciliation, and completion lanes, but they do not grant authority beyond the role contract below.
+
+## Review Ownership
+
+Review ownership is derived by the runtime from canonical run evidence. A lane records the owner, provider/model assignment when the owner is a role, whether the lane is required, whether its evidence can satisfy required gates, and compact artifact/event refs.
+
+- Verifier ownership is satisfied only by a main verifier response under the runtime loop.
+- Runtime QA/validation ownership is satisfied only by runtime-captured validation evidence and command metadata.
+- QA tester ownership is advisory model evidence and cannot satisfy runtime validation.
+- Review routing ownership is deterministic runtime policy evidence. It can require, skip, or sequence subjective lanes, but it cannot accept work by itself.
+- Critic ownership is advisory. The runtime may call the critic from a `critic_trigger` policy decision, but critic output cannot satisfy validation, verifier, or completion gates.
+- Same-run summons are sidecar evidence and remain read-only.
+- Same-run fan-outs are grouped sidecar evidence and remain read-only.
+- Fixable QA, critic, or verifier findings can become a runtime-owned `revision_packet` handoff back to the implementer. The packet and derived revision trail do not grant reviewer edit power and do not satisfy validation or verifier gates.
+
+## Orchestrator
+
+The orchestrator owns the strategy, not the filesystem.
+
+Inputs:
+
+- user goal
+- repo context
+- constraints
+- role mapping
+- current state
+- worker results
+- verifier verdicts
+- critic feedback
+- budgets
+
+Allowed tools:
+
+- read run state
+- create plan
+- delegate task
+- request approval
+- ask for verification
+- ask for critique
+
+Disallowed by default:
+
+- direct file edits
+- direct shell commands
+- direct patch application
+
+Outputs:
+
+- plan
+- task assignments
+- approval request
+- continue/revise/abort decision
+- final synthesis
+
+## Implementer
+
+The implementer owns scoped changes.
+
+Inputs:
+
+- narrow task objective
+- allowed paths
+- relevant files
+- acceptance criteria
+- disallowed changes
+- testing hints
+
+Allowed tools:
+
+- read files
+- edit allowed files
+- run scoped commands
+- inspect diff
+
+Disallowed by default:
+
+- changing protected test assets without explicit approval
+- changing unrelated files
+- applying its own output to the final checkout
+- claiming acceptance
+
+Outputs:
+
+- changed files
+- diff summary
+- commands run
+- self-check notes
+- unresolved risks
+
+When a repair pass is delegated, inputs also include the latest `revision_packet` ref and compact repair objective. The implementer must treat it as a narrow patch brief, not permission to broaden scope or accept the work.
+
+## QA Tester
+
+The QA tester is a read-only model-assisted tester, usually a cheaper model such as Codex Spark.
+
+The runtime calls QA only when review routing requires behavior or regression review. A skipped QA lane must have a recorded routing reason; skipped QA never weakens deterministic validation or verifier requirements.
+
+Inputs:
+
+- user goal
+- current plan
+- diff summaries
+- runtime command metadata
+- validation artifacts
+- verifier or critic evidence when present
+
+Allowed tools:
+
+- read files
+- inspect diffs
+- inspect logs
+- recommend deterministic validation commands
+
+Disallowed:
+
+- editing files
+- changing tests
+- running or claiming command results unless the runtime captured them
+- satisfying runtime QA/validation gates
+- accepting work
+
+Outputs:
+
+- verdict: `pass`, `needs_revision`, `needs_more_evidence`, or `blocked`
+- missed cases
+- suggested validation commands
+- product or regression risks
+- summary grounded in runtime evidence
+
+## Verifier
+
+The verifier owns independent assessment.
+
+The current routing policy keeps verifier review required for implementation runs when a verifier is assigned. If the verifier role is missing, the runtime stops for user review instead of completing the run.
+
+Inputs:
+
+- user goal
+- acceptance criteria
+- diff
+- changed files
+- raw test logs
+- runtime command metadata
+- implementer notes
+
+Allowed tools:
+
+- read files
+- inspect diffs
+- inspect logs
+- request deterministic commands through runtime
+
+Disallowed:
+
+- editing files
+- changing tests
+- applying patches
+- accepting unverifiable claims
+
+Outputs:
+
+- verdict: `approve`, `revise`, `abort`, or `ask_user`
+- evidence
+- failed criteria
+- recommended next action
+
+## Critic
+
+The critic challenges the plan or patch.
+
+The runtime may invoke the critic automatically when QA, verifier, or deterministic validation evidence indicates risk. That invocation is recorded as a `critic_trigger` artifact with a reason code and evidence refs.
+
+Best used for:
+
+- high-risk tasks
+- architectural changes
+- security-sensitive work
+- unclear product behavior
+- provider disagreement
+
+Outputs:
+
+- risks
+- missing cases
+- alternate designs
+- blocking concerns
+- non-blocking concerns
+
+The critic must not edit files, apply patches, mark tests as passed, or approve completion.
+
+## Integrator
+
+The integrator applies approved changes.
+
+The integrator should be deterministic runtime code when possible, not a general model agent.
+
+Responsibilities:
+
+- apply approved patch
+- verify target checkout state
+- ensure no unrelated files are included
+- capture final diff

package/docs/RUNTIME_LOOP.md

@@ -0,0 +1,240 @@
+# Runtime Loop
+
+TheHood runs a bounded agent loop. The loop is stateful, inspectable, and controlled by runtime rules rather than model habit.
+
+## Loop Summary
+
+```text
+1. Receive user goal
+2. Inspect repo and constraints
+3. Ask orchestrator for plan
+4. Request user approval when needed
+5. Delegate scoped task to implementer
+6. Capture diff and implementation notes
+7. Run deterministic validation commands
+8. Write a runtime-owned review-routing artifact from changed paths, protected-path matches, validation evidence, and role state
+9. Ask the mapped read-only QA tester when routing requires behavior or regression review
+10. Ask verifier for verdict using raw evidence
+11. Ask critic when risk or ambiguity warrants it
+12. Write a revision packet and delegate repair when findings are fixable
+13. Ask user, abort, or integrate when runtime policy requires it
+14. Produce final report with evidence
+15. Reconcile planner state against implementation evidence when needed
+```
+
+Each provider call is preceded by a runtime-built directive artifact containing role instructions, prompt variables, tool permissions, and the expected output contract. The provider response must satisfy that contract before the runtime advances to the next state.
+
+Local command providers such as `codex-cli` and `claude-code` also write redacted stdout/stderr `log` artifacts plus a compact `provider_invocation` artifact after the command exits. The invocation artifact records role, provider/model, command args, workspace mode, sandbox or permission mode when available, exit code, timeout state, output lengths and refs, parse status, and any isolated patch ref. It proves the runtime actually spawned the local agent adapter, but it does not replace the provider response, validation logs, or verifier verdict.
+
+Provider directives include a `directiveAck` marker. Browser-backed adapters must require the current marker in the provider response before accepting schema-valid JSON, which prevents stale ChatGPT Web project or conversation context from being mistaken for the current run.
+
+The `AgentResponse` JSON envelope is deliberately mechanical. It carries status, a short summary, required role-control fields such as `action`, `status`, or `verdict`, refs, and the directive acknowledgement. Human-facing plans, reports, reviews, critique, rationale, acceptance criteria, and long next-step writeups should live in `data.<required_data_key>.markdown` as GitHub-flavored Markdown. Status surfaces expose only a bounded markdown preview plus the response artifact ref; the full response artifact remains the source of truth.
+
+The runtime also records typed `handoffs` on the run record whenever work crosses a meaningful boundary between roles, an approval gate mediates the next transition, or a run completes. Display labels such as `Agent 1 / Orchestrator`, `Agent 2 / Implementer`, and `Agent 3 / Verifier` are derived from runtime roles and assignments. They are inspectable lane labels, not new permissions or authority.
+
+Same-run summons are read-only sidecar calls attached to an existing run. A summon carries an explicit brief, kind such as `qa` or `critique`, optional one-call provider assignment, constraints, and artifact refs. The runtime records the handoff and provider artifacts, but the summoned agent does not advance the main state machine or gain edit authority. Model-backed summon providers still pass through provider-invocation approval; autopilot can auto-approve that bounded gate when policy allows it.
+
+Same-run fan-out is a bounded group of summons attached to one run. The current runtime executes fan-out items sequentially so provider approval gates stay explicit and auditable, then writes a compact `fanout` artifact with item statuses, artifact refs, and bounds. Repo config can lower the fan-out item cap through `defaults.fanoutMaxItems`, while the runtime hard cap remains 8. An active approval gate stops later fan-out items until the gate is handled, but a contained advisory provider failure is recorded and later read-only items can still run. Fan-out is an evidence fan-in surface, not a scheduler: grouped responses remain sidecar evidence and cannot satisfy required verifier or runtime QA/validation lanes.
+
+Review lanes are runtime-derived gate metadata, not separate schedulers. The runtime derives verifier, runtime QA/validation, QA tester, and critic lanes from existing canonical evidence such as verifier responses, validation command artifacts, tool events, QA tester responses, critic responses, and read-only summon responses. Each lane carries bounded ownership metadata: owner label, role or runtime owner, provider/model assignment when known, required or optional status, current state, compact summary, and artifact/event refs. Final reports and progress packets expose those lanes so CLI, MCP, TUI, and future app surfaces can display reviewer/tester/QA/critic state without owning orchestration logic. A summoned agent can add read-only sidecar evidence, but a summon does not satisfy or replace a required verifier or runtime QA/validation lane.
+
+Critic triggers are runtime decisions, not model decisions. When QA, verifier, or deterministic validation evidence indicates risk, the runtime can invoke the configured read-only critic and write a `critic_trigger` artifact with the reason code, source roles, evidence refs, and critic response ref. The critic can recommend revision or missing evidence, but it cannot edit, satisfy validation, approve completion, or replace verifier ownership.
+
+Review routing is a runtime decision, not a model decision. After deterministic validation evidence is captured, the runtime writes a `review_routing` artifact with a conservative risk tier, required lanes, skipped-role reasons, and compact signals. The first policy slice keeps verifier review required for implementation runs, gates model-assisted QA by risk, and keeps critic escalation controlled by critic policy. Low risk is intentionally narrow, such as docs/copy-only changes with passing deterministic validation; runtime, provider, approval, artifact, CLI/TUI behavior, MCP, protected-path, dependency, network, schema, or validation changes route to stronger review.
+
+Revision packets are runtime repair handoffs, not reviewer authority. When QA returns `needs_revision`, verifier returns `revise`, or critic returns `needs_revision`, the runtime writes a compact `revision_packet` artifact and moves the run back to `implementing` with that packet in the implementer directive context. The next QA/verifier pass must use fresh post-repair runtime evidence. Verifier `ask_user` or `abort`, protected test gates, unsafe critic feedback, max-iteration failures, and other hard policy gates still stop instead of silently revising.
+
+Revision trails are runtime-derived visibility over that repair path. A trail item links the revision packet, delegation event, implementer repair response, post-repair validation artifacts, review responses, handoff refs, and terminal completion event when present. It lets CLI, MCP, TUI, final reports, and progress packets show whether a repair is still active or already reviewed. It does not make stale pre-repair QA, validation, or verifier evidence valid for the post-repair pass.
+
+Loop responsibility schedules are runtime-derived visibility snapshots over the same canonical evidence. A schedule names the current planner/orchestrator, implementer, verifier, runtime QA/validation, model-assisted QA tester, critic, reconciliation, integration, operator approval, and completion responsibilities with compact owner, status, gate, artifact, event, and handoff refs. The schedule does not add permissions, call providers, satisfy gates, or replace the state machine; it lets CLI, MCP, TUI, and future app surfaces show who owns the next responsibility without duplicating orchestration logic.
+
+Crew lane trails are the product-facing version of those same evidence snapshots. The runtime derives `crewLanes` from loop responsibilities and review lanes so operators can see the hood as planner, builder, runtime QA, model QA tester, verifier, critic, integrator, approval, reconciliation, and completion lanes. Each lane includes authority (`edit`, `read_only`, `runtime`, or `operator`), required/advisory state, compact refs, and whether the lane can satisfy a gate. The Codex-facing `agentBoard` merges those dynamic lane snapshots with the configured role roster and provider health so app surfaces can render visible agent cards without owning orchestration logic. A derived dashboard artifact can expose the same board as bounded Codex-renderable cards and tables. Crew lanes, agent board cards, and dashboard artifacts are display and handoff evidence only; they do not schedule agents, grant tools, or make advisory sidecars authoritative.
+
+The headless loop runner is a repeat driver over the same runtime state machine. It repeatedly advances a run until terminal state, required manual approval, no progress, or a caller-supplied cycle cap. It does not approve manual gates, add roles, schedule sidecar evidence, or replace verifier/runtime QA ownership.
+
+## State Machine
+
+```text
+created
+  -> planning
+  -> awaiting_approval
+  -> delegating
+  -> implementing
+  -> verifying
+  -> critiquing
+  -> integrating
+  -> completed
+
+Any state
+  -> failed
+  -> aborted
+```
+
+## Iteration Inputs
+
+Every iteration should include:
+
+- current run state
+- original user goal
+- current plan
+- previous findings
+- current diff
+- raw command logs
+- verifier verdict
+- critic verdict when present
+- open questions
+- remaining budget
+- stop conditions
+
+## Stop Conditions
+
+The loop must stop when any of these are true:
+
+- success criteria are satisfied
+- max iterations reached
+- token budget reached
+- time budget reached
+- command failure requires user action
+- protected file change requires explicit approval
+- model output fails schema validation repeatedly
+- provider response status is `blocked` or `failed`
+- user aborts the run
+
+## Approval Gates
+
+User approval is required before:
+
+- editing files in a target repo unless the run mode already authorizes it
+- modifying tests, fixtures, snapshots, or evaluation files
+- installing dependencies
+- running commands with external side effects
+- using network access when the policy requires approval
+- invoking model-backed providers such as `chatgpt-web`, `claude-code`, or `codex-cli` for read-only repo work
+- sending runtime-captured repo context to browser or API model providers such as `chatgpt-web`, unless the user's external transfer policy auto-approves the manifest
+- sending runtime-captured progress or memory packets to browser or API model providers, unless the user's external transfer policy auto-approves the manifest
+- applying a worker patch to the main checkout
+- continuing to verification after an applied worker patch changes protected test, fixture, snapshot, or eval paths
+- switching orchestrator or verifier mid-run for an active task
+
+When `approvalPolicy.mode` is `autopilot`, the user has pre-authorized the runtime to approve bounded low-risk gates without another prompt. Autopilot may approve provider invocation, implementation start, external transfers that pass transfer-manifest policy, isolated patch application, and runtime-owned revision packet repair while the provider-call budget allows. It must still stop for secret-risk transfers, protected test/fixture/snapshot/eval changes, destructive or dependency/network commands that require explicit command approval, dirty-checkout integration blockers, max-iteration failures, verifier `ask_user` or `abort`, and unsafe critic outcomes.
+
+Codex or tenant host-policy gates happen before TheHood can invoke an external model-backed provider. The runtime cannot auto-approve those gates, but MCP clients should call `thehood_model_access` first so the user sees a local-only packet with destinations, data boundary, approval copy, and fallback paths instead of a repeated long disclosure prompt.
+
+When an approval reason includes an exact phrase such as `Approval message must mention "apply isolated patch"`, the runtime enforces that phrase before recording an approving transition.
+
+Before sending repo context or a progress packet to a browser or API provider, the runtime writes a `transfer_manifest` artifact. The approval gate points at that manifest so CLI, MCP, TUI, and future app surfaces can show the destination provider, purpose, source artifacts, byte counts, hashes, risk class, exact approval phrase, and bounded preview before anything leaves the machine. If the user configures `approvalPolicy.mode: auto_low_risk`, `approvalPolicy.mode: autopilot`, or `externalTransfers: auto_low_risk`, bounded transfers that do not have `secret_risk` can be auto-approved; the runtime still records the manifest, approval event, and `approval_auto_approved` event.
+
+`maxIterations` is enforced from persisted provider responses. If the next transition would call another provider after the run has already recorded `maxIterations` agent responses, the runtime fails closed with reason `max_iterations`.
+
+## Runtime-Owned Evidence
+
+The runtime captures evidence directly:
+
+- git status before and after
+- diff before and after each worker
+- command and args
+- cwd
+- exit code
+- stdout
+- stderr
+- duration
+- tool permission decision
+- protected path classification
+- final report artifacts for completed runs
+- progress packet artifacts for later planner reconciliation
+- provider invocation artifacts for local Codex CLI and Claude Code adapter executions
+- derived review ownership metadata for verifier, runtime QA/validation, model-assisted QA tester, critic, and read-only summon evidence
+- review routing artifacts explaining risk tier, required lanes, skipped roles, and routing reasons
+- critic trigger artifacts explaining why an advisory critic was called
+- revision packet artifacts explaining why repair was delegated back to the implementer
+- revision trail items linking repair delegation to post-repair validation and review
+- external transfer manifest artifacts before approved provider transfers
+- typed handoff records for role delegation, approval mediation, and completion
+
+Models may summarize evidence, but summaries are not authoritative.
+
+## Memory
+
+TheHood's memory is canonical runtime state, not provider session context. Exact artifacts, run records, command logs, diffs, approvals, verifier verdicts, and final reports are authoritative. Summaries, vector memories, graph memories, and model reflections are derived navigation layers.
+
+Provider directives should assume that browser and API conversation context may be stale or empty. The runtime rehydrates providers from bounded packets that point back to exact artifacts.
+
+Each provider directive includes a bounded `canonicalMemory` object. It is a refs-only project memory index containing the current run snapshot, recent run summaries, and latest progress packet, reconciliation, repo context, provider execution, final report, review routing, and transfer manifest refs when available. It does not include large artifact bodies. Providers must treat this runtime-owned memory as authoritative and ignore stale provider session context unless that context is repeated in the directive.
+
+## Final Reports
+
+Completed read-only and verified implementation runs attach a `report` artifact with `kind: "final_report"`. The report includes the run goal, final state, stop reason, completing role, artifact refs, command metadata, approval events, bounded review ownership lanes, bounded crew lanes, and bounded revision trail items. The runtime also stores a bounded progress packet artifact after completion so a later planner reconciliation step can ask for external-transfer approval using an exact artifact ref.
+
+Run status insights expose the latest progress packet, reconciliation, repo context, provider execution, final report, and transfer manifest refs. They also expose bounded revision trails, crew lane trails, loop responsibility schedules, and operator next actions derived by the runtime from run state, approvals, provider waits, terminal state, revision handoffs, and review ownership lanes. Revision trails, crew lanes, loop schedules, and operator next actions are navigation aids over canonical artifacts; they do not replace artifact reads when a reviewer needs the full evidence and they do not weaken approval policy.
+
+MCP host responses are compact by default so long TheHood sessions do not exhaust the Codex conversation context with repeated status dumps. Default MCP outputs include run state, counts, latest artifact refs, recent events, compact insights, and bounded agent-board cards. Full run evidence remains in `.thehood` artifacts and run records; MCP callers can request `detail: "full"` on runtime tools or read exact artifact refs through `thehood_read_artifact` when they intentionally need the verbose payload.
+
+Provider status is also authoritative. A worker response with `blocked` pauses at an approval gate. A worker response with `failed` fails the run. The runtime must not advance blocked or failed implementation into verification.
+
+## Planner Reconciliation
+
+Planner reconciliation closes the loop after a plan has been implemented and verified. The runtime builds a progress packet from canonical artifacts, applies the user's external transfer approval policy, sends the packet to the selected planner or orchestrator after approval, validates the response, and stores the result as a reconciliation artifact.
+
+Reconciliation should answer which plan items are complete, which criteria remain open, whether the implementation deviated from the plan, and what the next slice should be. It is advisory; runtime evidence and approval gates remain authoritative.
+
+## Failure Classes
+
+Verifier and runtime failures should be classified into stable categories:
+
+- `test_failure`
+- `lint_failure`
+- `typecheck_failure`
+- `build_failure`
+- `schema_failure`
+- `permission_denied`
+- `approval_required`
+- `provider_error`
+- `ambiguous_goal`
+- `unsafe_action`
+- `budget_exhausted`
+- `unknown_failure`
+
+## Integration Rule
+
+Only the runtime applies approved changes to the target checkout.
+
+Implementers can produce patches. Local CLI implementers run in isolated git worktrees by default; TheHood captures their diff as a run artifact and stops before applying it. After explicit approval, deterministic runtime code applies the patch to the target checkout, captures a runtime-owned integration report artifact, and only then proceeds toward verification. If the integrated patch changes protected test, fixture, snapshot, or eval paths, the runtime stops for a separate approval before verification. Implementers do not get to self-merge.
+
+## Current Loop
+
+The current implementation can advance approved runs using the deterministic `stub` provider:
+
+```text
+delegating
+  -> orchestrator response
+  -> orchestrator response schema validation
+  -> implementing
+  -> implementer response
+  -> implementer response schema validation
+  -> awaiting_approval when an isolated patch artifact must be applied
+  -> integrating
+  -> awaiting_approval when integrated protected paths need separate approval
+  -> verifying
+  -> git evidence capture
+  -> package validation command capture
+  -> review routing artifact capture
+  -> mapped QA tester response when required by routing
+  -> critic response when runtime trigger policy detects QA, verifier, or validation risk
+  -> revision packet and implementer repair pass when QA, critic, or verifier returns a fixable revision finding
+  -> verifier response
+  -> verifier response schema validation
+  -> final report and progress packet artifacts
+  -> completed or awaiting_approval
+```
+
+ChatGPT Web is wired through a user-configured bridge command. API model providers are not wired yet. Local Codex CLI and Claude Code adapters are available through the same directive and response-validation contract.
+
+Read-only runs can also execute a mapped guest role directly:
+
+- `plan` uses `planner` when assigned, otherwise `orchestrator`
+- `research` uses `researcher` when assigned, otherwise `orchestrator`
+- `review` uses `critic` when assigned, otherwise `orchestrator`
+
+For read-only runs, model-backed providers such as `chatgpt-web`, `claude-code`, and `codex-cli` require provider-invocation approval before the first provider call unless autopilot policy auto-approves that bounded gate. When a direct read-only role or same-run summon uses `chatgpt-web`, local git reports a GitHub remote, a clean checkout, and `HEAD` matching the tracked upstream ref, and the active ChatGPT Web bridge GitHub connector surface is confirmed, the runtime attaches a refs-only `remote_context` artifact before the provider call. When a read-only orchestrator or planner returns `action: "delegate"` to a repo reader or inspector, the runtime treats that as an evidence request and applies that same confirmed GitHub connector route before falling back to local context capture. When it returns a ready handoff to another configured read-only role such as `planner`, `researcher`, `qa`, `verifier`, or `critic` with `requiresMoreEvidence` not set to true, the runtime records a role handoff and invokes that role instead of recapturing repo context. If the target read-only role is not assigned, the runtime stops at an explicit missing-role approval gate. A `remote_context` artifact instructs ChatGPT Web to use its GitHub connector at the exact commit instead of sending local file excerpts. Local runtime artifacts and checkout state remain authoritative, and the runtime falls back to deterministic local capture for local-only, dirty, unpushed, non-ChatGPT, or unconfirmed ChatGPT Web GitHub connector routes. Local capture writes a bounded `repo_context` artifact using deterministic filesystem reads. For browser or API model providers such as `chatgpt-web`, `openai-api`, and `anthropic-api`, the runtime then writes a `transfer_manifest` artifact before sending local repo context back to the provider. Manual policy stops at a second approval gate; auto-low-risk transfer policy and autopilot can auto-approve bounded non-secret manifests while still recording the manifest, approval event, and `approval_auto_approved` event. If the role requests another delegation after a local context pack exists, the runtime captures a follow-up context only when the structured decision names concrete repo paths that were not already captured or were previously captured only as truncated excerpts. If the role requests another delegation after a remote connector context already exists, the runtime stops at an approval gate rather than looping. Provider directives rehydrate local repo context from all captured context artifacts, assembling continuation chunks into one ordered excerpt per path, and include any refs-only remote connector context separately. Broad or fully duplicate repeated evidence delegations still stop at an approval gate instead of looping indefinitely.
+
+When a read-only orchestrator or planner returns `action: "delegate"` with `delegateTo: "implementer"` or `nextRole: "implementer"` and does not set `requiresMoreEvidence: true`, the runtime treats the response as a completed implementation handoff plan. A `plan` run then writes the usual final report and progress packet instead of recapturing repo context.

package/docs/SECURITY_AND_PRIVACY.md

@@ -0,0 +1,161 @@
+# Security And Privacy
+
+TheHood coordinates powerful local actions. Security and privacy must be designed into the runtime from the start.
+
+## Principles
+
+- User credentials stay local.
+- Provider sessions are never logged.
+- Runtime permissions are explicit.
+- Models do not receive secrets by default.
+- Dangerous actions require approval.
+- Logs are useful but redacted.
+- The system fails closed when unsure.
+
+## Secrets
+
+Secrets include:
+
+- API keys
+- browser cookies
+- session tokens
+- OAuth credentials
+- SSH keys
+- private repo URLs when sensitive
+- payment or customer data
+- private prompts containing confidential data
+
+Rules:
+
+- Do not print secrets to logs.
+- Do not include secrets in model context.
+- Redact environment variables by default.
+- Store provider credentials using OS keychain or provider CLI config when possible.
+- Treat custom provider:model aliases as user preference only; they do not bypass provider access controls, command readiness, approval gates, or external transfer review.
+- Require explicit user approval before invoking model-backed providers for read-only repo work.
+- Require explicit user approval before sending runtime-captured repo context to browser or API model providers unless the user-configured external transfer policy auto-approves a bounded non-secret-risk manifest.
+- Require explicit user approval before sending runtime-captured progress, memory, or reconciliation packets to browser or API model providers unless the user-configured external transfer policy auto-approves a bounded non-secret-risk manifest.
+- Treat Codex or tenant external-disclosure gates as outside runtime control. TheHood may provide a local-only model-access preflight packet and compact approval copy, but it must not bypass host policy or repeatedly ask the user to approve the same blocked disclosure in new wording.
+
+## Browser-Based Providers
+
+The ChatGPT Web adapter is sensitive because it depends on a user-authenticated browser session.
+
+Rules:
+
+- Use an isolated browser profile when possible.
+- Prefer the TheHood-managed persistent Chrome profile over the user's main Chrome profile.
+- Do not export cookies.
+- Do not write session tokens to disk.
+- Do not bypass provider restrictions.
+- Detect model availability visibly and fail if uncertain.
+- Capture only visible model outputs needed for the run.
+- Do not invoke ChatGPT Web for repo work until the user explicitly approves that provider invocation.
+- Do not send bounded repo context back to ChatGPT Web until the user explicitly approves that external context transfer or has configured low-risk external transfer auto-approval.
+- For clean pushed GitHub repos, ChatGPT Web may receive a refs-only `remote_context` artifact instead of local file excerpts only after the active bridge GitHub connector surface is confirmed. The directive tells ChatGPT to use its GitHub connector at the exact commit; it does not grant TheHood new GitHub access, attach ChatGPT apps, or bypass the user's ChatGPT connector permissions.
+- In autopilot mode, treat the user-configured approval policy as the approval source and still fail closed on secret-risk transfers, protected test changes, destructive commands, dependency installs, and dirty-checkout integration blockers.
+- Runtime-owned revision packets may route fixable reviewer findings back to the implementer, but unsafe critic feedback, verifier `ask_user` or `abort`, and protected-path gates must still stop for review.
+
+## Filesystem Safety
+
+The runtime must:
+
+- inspect dirty state before edits
+- avoid reverting unrelated user changes
+- isolate worker changes in worktrees when possible
+- enforce allowed and disallowed paths
+- block protected test changes unless approved
+- run edit-capable local agents in isolated git worktrees by default and capture patch artifacts for review
+- require explicit approval before applying isolated worker patches to the target checkout
+- require separate approval before verifier review when an applied worker patch changes protected test, fixture, snapshot, or eval paths
+- require `THEHOOD_ALLOW_DIRECT_EDIT=1` before a local agent can edit the target checkout directly
+- keep repo-local runtime state in `.thehood/`, automatically add `.thehood/` and `.thehood-browser.json` to `.git/info/exclude` for git checkouts, and treat that state as private local evidence rather than source code
+
+## MCP Repo Gateway
+
+MCP repo gateway tools are read-only, bounded, and skip `.git`, `.thehood`, dependency/build output, and secret-looking paths.
+
+Rules:
+
+- Treat every repo gateway tool result as data disclosed to the connected MCP host.
+- Use trusted MCP hosts only, especially when connecting ChatGPT Developer Mode to private local repos.
+- Prefer Secure MCP Tunnel over public tunnels for private repos.
+- Keep write tools separate from read tools and gated by runtime approval.
+- Do not expose broad filesystem access; every path must stay relative to the configured repo root.
+
+## Command Safety
+
+Commands should be classified before execution:
+
+- read-only
+- local write
+- network
+- dependency install
+- destructive
+- credential-sensitive
+
+Approval is required for commands with risky side effects.
+
+## Logging
+
+Logs should include:
+
+- command
+- cwd
+- duration
+- exit code
+- redacted stdout
+- redacted stderr
+- permission decision
+
+Logs should not include:
+
+- raw cookies
+- API keys
+- hidden browser state
+- full secret-bearing environment
+
+## Memory Safety
+
+Memory is a control channel. Retrieved memories, reflections, and summaries can influence model decisions, so they must be treated as derived data rather than authority.
+
+Rules:
+
+- Preserve exact source artifacts before creating derived memories.
+- Keep provenance for every derived memory: source refs, run id, created timestamp, commit or repo state when applicable, and derivation method.
+- Prefer exact excerpts and artifact refs over summary-only memory packets.
+- Mark superseded or invalidated plan state instead of silently overwriting it.
+- Tell browser-backed providers to ignore stale provider session context and use only TheHood-supplied state.
+- Require browser-backed provider responses to acknowledge the current directive before accepting schema-valid output.
+- Keep directive-level `canonicalMemory` bounded and refs-only. It may name latest progress, reconciliation, repo context, final report, and transfer manifest artifacts, but it must not inline large artifact bodies.
+- GitHub connector repo context is also refs-only and requires a confirmed provider connector route before selection. It may name owner, repo, branch, upstream, and commit, but it must not inline local file bodies.
+- If future work sends larger memory bodies to browser or API providers, treat that as a `memory_packet` external transfer and require a transfer manifest before the data leaves the machine.
+- Keep advanced memory engines pluggable and rebuildable from canonical artifacts.
+
+## External Transfer Review
+
+Before local repo context bodies or runtime memory cross a browser or API provider boundary, TheHood should create a transfer manifest and point the approval gate at it. Confirmed refs-only GitHub connector context names remote coordinates instead of local file bodies; it is recorded as a `remote_context` artifact and does not replace transfer manifests for local context packs.
+
+The manifest records:
+
+- destination provider and role
+- transfer purpose
+- source artifact refs
+- byte counts and hashes
+- risk class
+- exact approval phrase
+- bounded preview of the artifact content
+
+Approval should be based on that manifest. Manual approval is the default. When `externalTransfers` is set to `auto_low_risk`, the runtime can auto-approve bounded transfers whose risk class is not `secret_risk`; it still records the manifest and an approval event before sending. The provider response, transfer manifest, and source artifacts remain separate so a later reviewer can distinguish what was sent from what the provider concluded.
+
+## Public Repo Boundary
+
+The public repo should not contain:
+
+- real provider credentials
+- personal browser profiles
+- private prompts
+- run logs from private repos
+- hardcoded local paths as defaults
+
+Fixtures should be synthetic.